README

Carbon.Pipeline 是 esbuild 和 PostCSS 的美味融合，形成一个功能齐全、超快的现代 JavaScript 和 CSS 打包器，用于 Flow 框架和 Neos CMS。

入门指南

首先，感谢您想尝试这个构建栈！如果您错过了一个✨功能或发现了一个🐛错误，请随时 提交问题。

通过 composer 安装

运行 composer require carbon/pipeline --dev。在安装过程中，某些文件（如果尚未存在）将被复制到您的根目录。安装包后，运行命令 install 安装 package.json 中定义的所需包。在安装前，您可以根据需要修改和更改依赖项 👍

在不使用 Neos 的情况下在自定义项目中独立使用

Carbon.Pipeline 也可以是您非 Neos 项目的完美选择。请考虑事先安装 composer 包 neos/composer-plugin，以便将 Carbon.Pipeline 安装在 Build/Carbon.Pipeline 下的正确目录。

手动安装

如果您想对构建栈进行重大调整，您还可以 下载代码的 zip 文件 并将其放入 Build/Carbon.Pipeline 文件夹中。转到 Carbon.Pipeline/RootFiles/Global 和 Carbon.Pipeline/RootFiles/JavaScript 或 Carbon.Pipeline/RootFiles/TypeScript，将文件复制到您的根目录（不要忘记以点开头的隐藏文件）。完成后，运行命令 install 安装 package.json 中定义的所需包。在安装前，您可以根据需要修改和更改依赖项 👍

选择包管理器

您可以选择不同的包管理器： npm、Yarn 和超快且节省磁盘空间的 pnpm。您可以通过运行命令 pnpm setPackageManager、npm run setPackageManager npm 或 yarn setPackageManager yarn 来设置您喜欢的包管理器。脚本不需要任何依赖项，因此您可以在 install 命令之前运行它。默认包管理器为 pnpm

将文件添加到构建栈

Carbon.Pipeline 假定以下项目目录结构用于资源

在以下配置位置下：

• Resources/Private：输入文件
• Resources/：输出文件

整个配置，包括要构建哪些文件，都在 pipeline.yaml 中配置。默认值在 defaults.yaml 中设置，并与您的配置合并。在 packages 键下，您可以添加包含包设置的数组，或者如果您只有一个条目，可以直接添加配置

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

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

如果您只有一个文件，可以直接传递，无需创建数组

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

如果您没有设置文件，则从输入文件夹中获取所有可解析的文件进行渲染。以下划线 (_) 开头的文件将被忽略。

packages:
  package: Vendor.Bar

要更改输入和/或输出文件夹，可以使用 folder 选项

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

此外，您可以将文件写入另一个包

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

如果您想在 Neos 中玩转多站点，也可以将文件写入多个包

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

包条目有以下选项

以下是文件夹的默认值

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

以下是构建选项的默认值

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

可以在 folder.output 键下调整目标文件夹。如果您想为所有包更改默认值，也可以在您的 pipeline.yaml 中全局设置

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

buildDefaults:
  sourcemap: false
  format: esm

请参阅 defaults.yaml 文件以获取所有选项。

如果您设置了带有 JavaScript 模块后缀的条目文件（.mjs、.mjsx、.mts 或 .mtsx），则此文件的格式将强制为 esm。与 commonJS 相同：如果您设置了带有 JavaScript commonJS 后缀的条目文件（.cjs、.cjsx、.cts 或 .ctsx），则此文件的格式将强制为 cjs。例如，如果您有以下数组 ["Main.js", "Module.mjs", "CommonJS.cjs"]，并且没有特定的格式设置，则 Main.js 的格式将为 iife，Module.mjs 的格式将为 esm，而 CommonJS.cjs 的格式将为 cjs。

任务

由于您可以选择您喜欢的包管理器，因此您必须将任务名称与相应的名称（pnpm、yarn 或 npm run）一起使用

有五个预定义的主要任务

任务被分割，因此它们可以并行运行。但是，您也可以单独运行它们

可扩展性

当然，您也可以在您的 package.json 文件的 scripts 部分添加自己的任务。例如，如果您有 Neos UI 自定义编辑器并且想在同一个地方启动所有任务，您可以这样添加它们

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

请注意，根据所选的任务管理器，设置选项的语法可能不同。例如，要设置当前工作目录，对于 yarn，您必须设置 --cwd，对于 pnpm，设置 --dir 或 -C，对于 npm，设置 --prefix。

由于任务以 build:、分别以 watch: 或 pipeline: 开头，因此任务将包含在相应的根命令中。在这个例子中，build、watch 或 pipeline。如果您想玩得更疯狂，甚至可以混合不同的任务管理器。

文件压缩

在生产模式（build）下，文件也会使用 gzip 和 brotli 进行压缩。您可以在 buildDefaults.compression 键下编辑压缩级别。默认情况下，设置为最高压缩级别。要完全禁用压缩，您可以将其设置为 false

buildDefaults:
  compression: false

或者，如果您只想禁用其中一个，可以将条目设置为 false

buildDefaults:
  compression:
    gzip: false

从 DistributionPackages 和其他 Packages 导入文件

默认情况下，已预定义了两个别名：DistributionPackages 和 Packages。这样您就可以导入（CSS 和 JS）文件，如下所示从其他包中

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

感谢自定义的 resolve 函数，您还可以在 CSS 导入中使用 globbing： @import "Presentation/**/*.pcss";

修改配置文件

在某些设置中，您可能需要使用不同的配置文件进行多个配置。在这种情况下，您可以在 package.json 文件中的 scripts 部分设置其他配置文件

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

在这个示例中，使用的是 pipelineCustom.yaml 而不是 pipeline.yaml。

CSS

Sass

如果您想使用 Sass（.scss 或 .sass 文件），则必须安装 sass 和 node-sass-tilde-importer

对于 pnpm

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

对于 Yarn

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

对于 npm

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

有两种方法可以从 node_modules 中导入文件（以 bootstrap 为例）

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

sassOptions:
  quietDeps: true

PostCSS

此模板附带各种 PostCSS 插件。您可以根据需要删除一些或添加您喜欢的包。配置位于 .postcssrc.mjs。这些文件的扩展名应该是 .pcss。

将自定义选项传递给您的 PostCSS 配置文件

您可以通过 postcssOptions 键将自定义选项传递给您的 PostCSS 配置文件。在这个例子中，您可以在您的 PostCSS 配置文件（.postcssrc.mjs）中使用 ctx.prefix 访问 prefix 键。

postcssOptions:
  prefix: true

使用 postcss resolve() 函数

您可以在 css/scss 文件中使用 resolve() 来从包的 Resources/Public 加载资源（例如图像）。路径将在编译时解析。

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

解析为

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

如果您选择将您的 Packages 按照子文件夹排序在 DistributionPackages 中，您可以添加此设置以确保路径被正确重写

postcssOptions:
  additionalPackagePathPrefixes:
    - Sites
    - Plugins

这确保了生成的路径（例如 /_Resources/Static/Packages/(Sites|Plugins)/Your.Package/.../）将被正确解析，从路径中删除子文件夹。

PostCSS 插件

Tailwind CSS

此设置附带 Tailwind CSS，这是一个高度可定制的、低级别的 CSS 框架。示例配置位于 tailwind.config.mjs。CSS 文件清理的设置也已配置。有关控制文件大小的更多信息，请参阅 此处。由于 CSS 打包是通过 PostCSS 的 JavaScript API 完成的，因此 Tailwind CSS 的 即时模式 运行得非常好。要删除特定包，您可以在 pipeline.yaml 中使用此模式

buildDefaults:
  purge:
    - DistributionPackages/**/(Private|NodeTypes)/**/*.{fusion,html,js,jsx,ts,tsx,mjs,mjsx,mts,mtsx,cjs,cjsx,cts,ctsx,svelte,vue}
    - "!DistributionPackages/Package.ToRemove"

顺便说一句：将 Alpine.js 与 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:
          css: true

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

实时重新加载

如果您想使用实时重新加载，可以使用Browsersync。

要安装它，请运行pnpm add --global browser-sync，yarn global add browser-sync或npm install -g browser-sync。

然后您必须使用browser-sync init创建一个初始配置。之后，您需要调整创建的bs-config.js文件。您可以调整每个参数，但您需要设置的参数是files和proxy

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

如果您还想在更改fusion或模板文件时重新加载页面，您也可以这样做

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

请确保您设置了正确的代理，并使用相应的协议（https://或http://），具体取决于您的配置。为了更好地了解参数，您可以从文件中删除未更改的值。

要启动Browsersync，您可以运行browser-sync start --config bs-config.js。如果您想与watch一起启动，可以将以下行添加到scripts部分

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