Skip to content

Commit

Permalink
Docs: Update Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jonnitto
jonnitto committed Apr 22, 2024
1 parent 424f32a commit f2f962c
Showing 1 changed file with 60 additions and 101 deletions.
161 changes: 60 additions & 101 deletions Readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Carbon.Pipeline is also a perfect choice for your non-Neos projects. Consider in

### Manual install

If you want to make significant adjustments to the build stack, you can also [download the code as zip file][main.zip] and put it in the `Build/Carbon.Pipeline` folder. Go to `Carbon.Pipeline/Installer/Distribution/Defaults` and copy the files to your root folder (Don't forget the hidden files, starting with a dot). After this is done, run the command `install` to install the required packages defined in `package.json`. Feel free to modify and change dependencies before installing 👍
If you want to make significant adjustments to the build stack, you can also [download the code as zip file][main.zip] and put it in the `Build/Carbon.Pipeline` folder. Go to `Carbon.Pipeline/RootFiles/Global` and `Carbon.Pipeline/RootFiles/JavaScript` or `Carbon.Pipeline/RootFiles/TypeScript`, copy the files to your root folder (Don't forget the hidden files, starting with a dot). After this is done, run the command `install` to install the required packages defined in `package.json`. Feel free to modify and change dependencies before installing 👍

### Choose a package manager

Expand Down Expand Up @@ -177,35 +177,37 @@ If you set an entry file with the javascript module suffix (`.mjs`, `.mjsx`, `.m

There are five predefined main tasks:

| Command | Description | Command |
| ------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `watch` | Start the file watcher | `concurrently -r $npm_package_config_packageManager:watch:*` |
| `dev` | Build the files once | `concurrently -r $npm_package_config_packageManager:dev:*` |
| `build` | Build the files once for production (with optimzed file size) | `concurrently -r $npm_package_config_packageManager:build:*` |
| `pipeline` | Run install, and build the files for production | `$npm_package_config_packageManager install;concurrently -r $npm_package_config_packageManager:pipeline:*` |
| `showConfig` | Shows the merged configuration from [`pipeline.yaml`] and [`defaults.yaml`] | `node Build/Carbon.Pipeline/showConfig.mjs` |
| `setPackageManager` | [Set your package manager.] | `node Build/Carbon.Pipeline/setPackageManager.js` |
| Command | Description | Command |
| ------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
| `watch` | Start the file watcher | `concurrently -r pnpm:watch:*` |
| `dev` | Build the files once | `concurrently -r pnpm:dev:*` |
| `build` | Build the files once for production (with optimzed file size) | `concurrently -r pnpm:build:*` |
| `pipeline` | Run install, and build the files for production | `pnpm install;concurrently -r pnpm:pipeline:*` |
| `showConfig` | Shows the merged configuration from [`pipeline.yaml`] and [`defaults.yaml`] | `node Build/Carbon.Pipeline/showConfig.mjs` |
| `setPackageManager` | [Set your package manager.] | `node Build/Carbon.Pipeline/setPackageManager.js` |

The tasks are split up, so they can run in parallel mode. But you can also run them separately:

| Command | Description | Command |
| ---------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| `watch:js` | Start the file watcher for JavaScript files | `node Build/Carbon.Pipeline/esbuild.mjs --watch` |
| `watch:css` | Start the file watcher for CSS files | `node Build/Carbon.Pipeline/postcss.mjs --watch` |
| `dev:js` | Build the files once for JavaScript files | `node Build/Carbon.Pipeline/esbuild.mjs` |
| `dev:css` | Build the files once for CSS files | `node Build/Carbon.Pipeline/postcss.mjs` |
| `build:js` | Build the JavaScript files once for production | `node Build/Carbon.Pipeline/esbuild.mjs --production` |
| `build:css` | Build the CSS files once for production | `node Build/Carbon.Pipeline/postcss.mjs --production` |
| `pipeline:build` | Build the files once for production (with optimzed file size) | `concurrently -r $npm_package_config_packageManager:build:*` |
| Command | Description | Command |
| ---------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
| `watch:js` | Start the file watcher for JavaScript files | `node Build/Carbon.Pipeline/esbuild.mjs --watch` |
| `watch:css` | Start the file watcher for CSS files | `node Build/Carbon.Pipeline/postcss.mjs --watch` |
| `dev:js` | Build the files once for JavaScript files | `node Build/Carbon.Pipeline/esbuild.mjs` |
| `dev:css` | Build the files once for CSS files | `node Build/Carbon.Pipeline/postcss.mjs` |
| `build:js` | Build the JavaScript files once for production | `node Build/Carbon.Pipeline/esbuild.mjs --production` |
| `build:css` | Build the CSS files once for production | `node Build/Carbon.Pipeline/postcss.mjs --production` |
| `pipeline:build` | Build the files once for production (with optimzed file size) | `concurrently -r pnpm:build:*` |

### Extendibility

Of course, you can also add your own tasks in the `scripts` section of your `package.json` file. For example, if you have a Neos UI custom editor and want to start all your tasks in one place, you can add them like this:

```
"build:editor": "$npm_package_config_packageManager --dir DistributionPackages/Foo.Editor/Resources/Private/Editor/ build",
"watch:editor": "$npm_package_config_packageManager --dir DistributionPackages/Foo.Editor/Resources/Private/Editor/ watch",
"pipeline:editor": "$npm_package_config_packageManager --dir DistributionPackages/Foo.Editor/Resources/Private/Editor/ install",
```json
{
"build:editor": "pnpm --dir DistributionPackages/Foo.Editor/Resources/Private/Editor/ build",
"watch:editor": "pnpm --dir DistributionPackages/Foo.Editor/Resources/Private/Editor/ watch",
"pipeline:editor": "pnpm --dir DistributionPackages/Foo.Editor/Resources/Private/Editor/ install",
}
```

> Be aware that you may have different syntax for settings options based on the chosen task manager
Expand Down Expand Up @@ -250,8 +252,10 @@ Thanks to a custom made `resolve` function, you can also use [globbing][glob] in

In some setups, you may need multiple configurations with different config files. In this edge case, you can set a other config file in your `scripts` section in your `package.json` file:

```
"build:custom:css": "node Build/Carbon.Pipeline/postcss.mjs --configFile=pipelineCustom.yaml"
```json
{
"build:custom:css": "node Build/Carbon.Pipeline/postcss.mjs --configFile=pipelineCustom.yaml"
}
```

In this example, `pipelineCustom.yaml` gets used instead of `pipeline.yaml`.
Expand Down Expand Up @@ -319,23 +323,23 @@ postcssOptions:

You can use `resolve()` in your css/scss files to load resources (eg images) from `Resources/Public` of the package. The path will be resolved at compile-time.

```
```css
.my-class {
background-image: resolve('Images/my-image.jpg')
}
```

resolves to

```
```css
.my-class {
background-image: url('/_Resources/Static/Packages/Your.Package/Images/my-image.jpg')
}
```

If you choose to order your Packages in DistributionPackages in subfolders, you can add this setting to ensure the paths are correctly rewritten:

```
```yaml
postcssOptions:
additionalPackagePathPrefixes:
- Sites
Expand Down Expand Up @@ -401,14 +405,27 @@ Sentry.init({
});
```

Make sure your [`.eslintrc`] has the global `FLOW` enabled:
Make sure your [`eslint.config.mjs`] has the global `FLOW` enabled:

```json
{
"globals": {
"FLOW": "readonly"
}
}
```js
import globals from "globals";
import pluginJs from "@eslint/js";
import prettierRecommended from "eslint-plugin-prettier/recommended";

export default [
pluginJs.configs.recommended,
prettierRecommended,
{
ignores: ["Build/", "Packages/", "**/Public/", "**/Resources/Private/Templates/", "*.noLinter.*"],
languageOptions: {
globals: {
...globals.browser,
...globals.node,
FLOW: "readonly",
},
},
},
];
```

</details>
Expand All @@ -435,67 +452,7 @@ esbuild:
<details>
<summary><strong>TypeScript</strong></summary>

If you want to use [TypeScript], add the following packages to `package.json`:

For [pnpm]:

```bash
pnpm add -D typescript @typescript-eslint/eslint-plugin
```

For [Yarn]:

```bash
yarn add --dev typescript @typescript-eslint/eslint-plugin
```

For [npm]:

```bash
npm add -D typescript @typescript-eslint/eslint-plugin
```

Add your `tsconfig.json` file; this is just an example:

```json
{
"include": ["DistributionPackages/**/Private/*"],
"exclude": [
"node_modules/*",
"DistributionPackages/**/Public/*",
"DistributionPackages/**/Private/Templates/InlineAssets*",
"Packages"
],
"compilerOptions": {
"baseUrl": "./",
"paths": {
"Packages/*": ["Packages/*"],
"DistributionPackages/*": ["DistributionPackages/*"]
}
}
}
```

To enable the correct linting, edit [`.eslintrc`]:

```json
{
"parser": "@typescript-eslint/parser",
"extends": [
"plugin:@typescript-eslint/recommended",
"eslint:recommended",
"plugin:prettier/recommended",
"prettier/@typescript-eslint"
],
"env": {
"es6": true,
"node": true
},
"globals": {
"FLOW": "readonly"
}
}
```
If you want to use [TypeScript], just choose the option TypeScript on the composer installation

</details>

Expand Down Expand Up @@ -781,8 +738,10 @@ Make sure you set the correct proxy with the corresponding protocol (`https://`

To start Browsersync you can run `browser-sync start --config bs-config.js`. If you want to start it together with `watch`, you can add the following line into the `scripts` section:

```
"watch:browsersync": "browser-sync start --config bs-config.js",
```json
{
"watch:browsersync": "browser-sync start --config bs-config.js",
}
```

[packagist]: https://packagist.org/packages/carbon/pipeline
Expand All @@ -792,7 +751,7 @@ To start Browsersync you can run `browser-sync start --config bs-config.js`. If
[postcss]: https://postcss.org
[open an issue]: https://github.com/CarbonPackages/Carbon.Pipeline/issues/new
[composer]: https://getcomposer.org
[`pipeline.yaml`]: Installer/Distribution/Defaults/pipeline.yaml
[`pipeline.yaml`]: RootFiles/Global/pipeline.yaml
[`defaults.yaml`]: defaults.yaml
[`builddefaults.compression`]: defaults.yaml#L31-L33
[esbuild format]: https://esbuild.github.io/api/#format
Expand All @@ -817,12 +776,12 @@ To start Browsersync you can run `browser-sync start --config bs-config.js`. If
[npm]: https://www.npmjs.com
[yarn]: https://yarnpkg.com
[pnpm]: https://pnpm.io
[`.eslintrc`]: Installer/Distribution/Defaults/.eslintrc
[`.postcssrc.mjs`]: Installer/Distribution/Defaults/.postcssrc.mjs
[`eslint.config.mjs`]: RootFiles/JavaScript/eslint.config.mjs
[`.postcssrc.mjs`]: RootFiles/Global/.postcssrc.mjs
[tailwind css]: https://tailwindcss.com
[just-in-time mode]: https://tailwindcss.com/docs/just-in-time-mode
[alpine.js]: https://github.com/alpinejs/alpine
[`tailwind.config.mjs`]: Installer/Distribution/Defaults/tailwind.config.mjs
[`tailwind.config.mjs`]: RootFiles/Global/tailwind.config.mjs
[tailwind file-size]: https://tailwindcss.com/docs/controlling-file-size
[sass]: https://sass-lang.com
[`sass`]: https://www.npmjs.com/package/sass
Expand Down

0 comments on commit f2f962c

Please sign in to comment.