Carbon.pipeline

Carbon.Pipeline is a delicious blend of esbuild and PostCSS to form a full-featured, ultra-fast modern Javascript and CSS bundler for Flow Framework and Neos CMS.

Getting started

First, thank you that you want to give this build stack a try! If you miss a ✨ feature or found a 🐛 bug, feel free to open an issue.

Install via composer

Run composer require carbon/pipeline --dev. Some files (if not already existing) will be copied to your root folder during the installation. After installing the package, run the command install to install the required packages defined in package.json. Feel free to modify and change dependencies before installing 👍

Standalone use in custom projects without Neos

Carbon.Pipeline is also a perfect choice for your non-Neos projects. Consider installing the composer package neos/composer-plugin beforehand to get Carbon.Pipeline installed in the correct directory under Build/Carbon.Pipeline.

Manual install

If you want to make significant adjustments to the build stack, you can also download the code as zip file 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

You can choose between different package managers: npm, Yarn and the ultra-fast and disk-space saving pnpm. You can set your favorite package manager by running the command pnpm setPackageManager, npm run setPackageManager npm or yarn setPackageManager yarn. The script behind it don't need any dependencies, so you can run it before the install command. The default package manager is pnpm

Add files to the build stack

Carbon.Pipeline assumes the following project directory structure for resources:

A configured location under

• Resources/Private: input files
• Resources/: output files

The whole configuration, including which files to build, is configured in pipeline.yaml. The default values are set in defaults.yaml and merged with your configuration. Under the key packages, you can either add an array with package settings or, if you have just one entry, you can directly add the configuration:

packages:
  - package: Vendor.Bar
    files:
      - Main.pcss
      - Main.js

# This is the same as
packages:
  package: Vendor.Bar
  files:
    - Main.pcss
    - Main.js

If you have just one file, you can pass this directly without creating an array:

packages:
  package: Vendor.Bar
  files: Main.js

If you don't set files, all parsable files from the input folder get rendered. Files that start with an underscore (_) will be ignored.

packages:
  package: Vendor.Bar

To change the input and/or the output folder, you can do this with the folder option:

packages:
  package: Vendor.Bar
  folder:
    input: Assets
    output:
      inline: Private/Templates
      style: Public
      script: Public
      module: Public
      commonJS: Public

Further, you can write the files to another package:

packages:
  package: Vendor.Bar
  folder:
    output:
      package: Vendor.Theme

If you want to go crazy with multi-sites in Neos, you can also write the files to multiple packages:

packages:
  package: Vendor.Bar
  folder:
    output:
      package:
        - Vendor.Theme
        - Vendor.Bar

A package entry has the following options:

These are the default values for the folders:

folder:
  input: Fusion
  output:
    inline: Private/Templates/InlineAssets
    style: Public/Styles
    script: Public/Scripts
    module: Public/Modules
    commonJS: Public/CommonJS

and these for the build options:

external: null
inline: false
sourcemap: true
format: iife
jsFileExtension:
  script: .js
  module: .mjs
  commonJS: .cjs

The target folders can be adjusted under the key folder.output. If you want to change the defaults for all your packages, you can also set this globally in your pipeline.yaml:

folder:
  input: Assets
  output:
    inline: Private/Templates
    style: Public
    script: Public
    module: Public
    commonJS: Public

buildDefaults:
  sourcemap: false
  format: esm

Please look at the defaults.yaml file for all the options.

If you set an entry file with the javascript module suffix (.mjs, .mjsx, .mts or .mtsx) the format of this file will be enforced to esm. The same with commonJS: If you set an entry file with the javascript commonJS suffix (.cjs, .cjsx, .cts or .ctsx) the format of this file will be enforced to cjs. E.g., if you have the following array ["Main.js", "Module.mjs", "CommonJS.cjs"], and have no specific setting for the format, Main.js will have the format iife, Module.mjs will have the format esm and CommonJS.cjs will have the format cjs.

Tasks

As you can choose your favorite package manager, you have to prepend the task name with the corresponding name (pnpm, yarn or npm run)

There are five predefined main tasks:

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

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": "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 To set the current work directory, for example you have to set --cwd for yarn, --dir or -C for pnpm and --prefix for npm.

Because the tasks start with build:, respectively with watch: or pipeline:, the tasks will be included in the corresponding root command. In this example, build, watch or pipeline. If you want to go crazy, you can even mix different task managers.

Compression of files

In production mode (build), the files also get compressed with gzip and brotli. You can edit the compression level under the key buildDefaults.compression. Per default, the highest compression level is set. To disable compression at all, you can set it to false:

buildDefaults:
  compression: false

Or, if you want to disable just one of them, you can set the entry to false:

buildDefaults:
  compression:
    gzip: false

Import files from DistributionPackages and other Packages

By default, two aliases are predefined: DistributionPackages and Packages. Like that you can import (CSS and JS) files from other packages like that:

import "DistributionPackages/Vendor.Foo/Resources/Private/Fusion/Main";
import "Packages/Plugins/Jonnitto.PhotoSwipe/Resources/Private/Assets/PhotoSwipe";

@import "DistributionPackages/Vendor.Foo/Resources/Private/Fusion/Main.pcss";
@import "Packages/Carbon/Carbon.Image/Resources/Private/Assets/Tailwind.pcss";

Thanks to a custom made resolve function, you can also use globbing in CSS imports: @import "Presentation/**/*.pcss";

Alter the configuration file

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"
}

In this example, pipelineCustom.yaml gets used instead of pipeline.yaml.

CSS

Sass

If you want to use Sass (.scssor .sass files) you have to install sass and node-sass-tilde-importer:

For pnpm:

pnpm add -D sass node-sass-tilde-importer

For Yarn:

yarn add --dev sass node-sass-tilde-importer

For npm:

npm add -D sass node-sass-tilde-importer

You have to ways to import files from node_modules (Example with bootstrap):

@import "node_modules/bootstrap/scss/bootstrap";
@import "~bootstrap/scss/bootstrap";

sassOptions:
  quietDeps: true

PostCSS

This template comes with a variety of PostCSS Plugins. Feel free to remove some or add your own favorite packages. The configuration is located in .postcssrc.mjs. The suffix of these files should be .pcss.

Pass custom options to you PostCSS config file

You can pass custom options to your PostCSS config file with key postcssOptions. In this example, you would access the key prefix with ctx.prefix in your PostCSS config file (.postcssrc.mjs).

postcssOptions:
  prefix: true

Use postcss resolve() function

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.

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

resolves to

.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:

postcssOptions:
  additionalPackagePathPrefixes:
    - Sites
    - Plugins

This ensures that the path that is generated (eg /_Resources/Static/Packages/(Sites|Plugins)/Your.Package/.../) will be correctly resolved, removing the subfolder from the path.

PostCSS Plugins

Tailwind CSS

This setup comes with Tailwind CSS, a highly customizable, low-level CSS framework. An example configuration is provided in tailwind.config.mjs. The setup for get the content for the CSS files is also configured. Read more about controlling the file size here. To remove a specific package, you could use this pattern in your pipeline.yaml:

buildDefaults:
  content:
    RemovePacakge: "!DistributionPackages/Package.ToRemove"

By default, following entries are pre-defined:

buildDefaults:
  content:
    DistributionPackages: DistributionPackages/**/(Private|NodeTypes)/**/*.{fusion,html,js,jsx,ts,tsx,mjs,mjsx,mts,mtsx,cjs,cjsx,cts,ctsx,svelte,vue}
    ignoreNodeModules: '!DistributionPackages/**/Private/**/node_modules'

The script put automatically all entries starting with an ! at the end of the list. You can control this setting by calling pnpm showConfig --path=buildDefaults.content

By the way: Alpine.js is excellent in combination with Tailwind CSS.

Javascript

esbuild:
  defineFlowSettings: Flownative.Sentry

Sentry.init({
  dsn: FLOW.Flownative.Sentry.dsn,
  release: FLOW.Flownative.Sentry.release,
  environment: FLOW.Flownative.Sentry.environment,
  integrations: [new Integrations.BrowserTracing()],
});

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",
            },
        },
    },
];

esbuild:
  options:
    pure:
      - console.log
      - console.pure

import * as React from "react";
render(<div />);

{
  "compilerOptions": {
    "jsxFactory": "h",
    "jsxFragmentFactory": "Fragment"
  }
}

pnpm add -D svelte svelte-preprocess esbuild-svelte @tsconfig/svelte

yarn add --dev svelte svelte-preprocess esbuild-svelte @tsconfig/svelte

npm add -D svelte svelte-preprocess esbuild-svelte @tsconfig/svelte

esbuild:
  plugins:
    svelte:
      enable: true
      # Name of the esbuild plugin for svelte
      # plugin: esbuild-svelte
      # Name of the preprocess plugin
      # preprocess: svelte-preprocess
      # Add here your options
      options:
        compilerOptions:
          # external or injected
          css: external

{
  "extends": "@tsconfig/svelte/tsconfig.json",
  "include": ["DistributionPackages/**/Private/*"],
  "exclude": [
    "node_modules/*",
    "__sapper__/*",
    "DistributionPackages/**/Public/*",
    "DistributionPackages/**/Private/Templates/InlineAssets*",
    "Packages"
  ],
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "Packages/*": ["Packages/*"],
      "DistributionPackages/*": ["DistributionPackages/*"]
    }
  }
}

pnpm add -D vue esbuild-plugin-vue3

yarn add --dev vue esbuild-plugin-vue3

npm add -D vue esbuild-plugin-vue3

esbuild:
  plugins:
    vue:
      enable: true
      # Name of the esbuild plugin for Vue
      # plugin: esbuild-plugin-vue3
      # You can pass your needed options here
      # options:

pnpm add -D @babel/core esbuild-plugin-babel

yarn add --dev @babel/core esbuild-plugin-babel

npm add -D @babel/core esbuild-plugin-babel

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "modules": false
      }
    ]
  ],
  "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
}

esbuild:
  plugins:
    babel:
      enable: true
      # You can pass your needed options here
      # options:

{
  "env": {
    "development": {
      "presets": [
        [
          "@babel/preset-env",
          {
            "modules": false
          }
        ]
      ],
      "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
    },
    "production": {
      "presets": [
        [
          "@babel/preset-env",
          {
            "modules": false
          }
        ]
      ],
      "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread", "transform-remove-console"]
    }
  }
}

defaults
ie 11
not dead

esbuild:
  additionalPlugins:
    esbuild-envfile-plugin:
      functionName: setup
      options: null

Live-Reloading

If you want to use live reloading, you can do this with Browsersync.

To install it run pnpm add --global browser-sync, yarn global add browser-sync, or npm install -g browser-sync.

Then you have to create an initial config with browser-sync init. After that, you need to adjust the created bs-config.js file. You can adjust every parameter, but the two parameter you need to set is files and proxy:

module.exports = {
  files: ["DistributionPackages/**/Public/**/*.css", "DistributionPackages/**/Public/**/*.js"],
  proxy: "http://your.local.domain",
};

If you want to also reload the page if a fusion or a template file gets changed, you can do so:

module.exports = {
  files: [
    "DistributionPackages/**/Public/**/*.css",
    "DistributionPackages/**/Public/**/*.js",
    "DistributionPackages/**/Private/**/*.fusion",
    "DistributionPackages/**/Private/**/*.html",
  ],
  proxy: "http://your.local.domain",
};

Make sure you set the correct proxy with the corresponding protocol (https:// or http://), depending on your setup. To create a better overview of the parameter, you can delete the not changed values from the file.

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",
}