From f2f962cae38c0679a54cb9d35be580a757ffa840 Mon Sep 17 00:00:00 2001 From: Jon Uhlmann Date: Mon, 22 Apr 2024 15:37:02 +0200 Subject: [PATCH] Docs: Update Readme --- Readme.md | 161 ++++++++++++++++++++---------------------------------- 1 file changed, 60 insertions(+), 101 deletions(-) diff --git a/Readme.md b/Readme.md index 1154692..ff50e69 100644 --- a/Readme.md +++ b/Readme.md @@ -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 @@ -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 @@ -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`. @@ -319,7 +323,7 @@ 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') } @@ -327,7 +331,7 @@ You can use `resolve()` in your css/scss files to load resources (eg images) fro resolves to -``` +```css .my-class { background-image: url('/_Resources/Static/Packages/Your.Package/Images/my-image.jpg') } @@ -335,7 +339,7 @@ resolves to 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 @@ -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", + }, + }, + }, +]; ``` @@ -435,67 +452,7 @@ esbuild:
TypeScript -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
@@ -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 @@ -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 @@ -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