@x.render/render-builder v1.3.0

@x.render/render-builder

中文文档

Introduce

A basic builder that integrates building tools such as webpack, Vite.

Usage

npm install @x.render/render-builder -D

Commands

render-builder provides two commands, start and build, for starting and compiling projects.

start

Use the start command to run the project and support cli args passing in

args

build.json is used by default. If you want to use a configuration file of type build.config(js \| ts \| mjs \| mts \| cjs \| cts), please use config to specify the configuration file path.

npx render-builder start --config=./build.config.js  --host=0.0.0.0 --port=3333

build

Use build command to run compilation and support cli args.

args

npx render-builder build --config=./build.config.js

Instructions for use

render-builder itself does not have any building capabilities, and it integrates webapck, vite and other building tools internally. render-builder is only responsible for providing unified running commands and unified paradigm plugins and presets, and determines which build tool to use based on the plugins and presets.

tips:(Currently only supports webpack)

Architecture diagram

Write a plugin

render-builder specifies the writing paradigm of the A simple plugin example suitable for webpack is as follows:

import {
  Compiler,
  ChainConfig,
  WebpackBuilderPluginClass,
} from "@x.render/render-builder";
type PluginOptions = Record<string, any>;

export default class DemoWebpackPlugin extends WebpackBuilderPluginClass {
  run(compiler: Compiler, config: ChainConfig, options: PluginOptions) {
    const { context } = compiler;
    const { command } = context;
    const mode = command === "start" ? "development" : "production";
    config.mode(mode);
    return config;
  }
}

All render-builder plugins must implement one of the three classes WebpackBuilderPluginClass, ViteBuilderPluginClass, and RollupBuilderPluginClass.Currently only WebpackBuilderPluginClass has a specific implementation.

Plug-ins written using WebpackBuilderPluginClass will have a getConfig static method,Plug-ins written using WebpackBuilderPluginClass will have a getConfig static method, which can be used to obtain the webpack-chain configuration inside the plug-in.

The run method in the plug-in must return config, which is convenient for other plug-ins to use or provided to rende-builder for compilation.

For example, the following code can obtain the webpack-chain configuration in DemoWebpackPlugin:

const demoConfig = DemoWebpackPlugin.getConfig(
  compiler,
  config,
  DemoWebpackPluginOptions
);

The compiler, config, and options parameters can be obtained in the run method of each plug-in, and these parameters can be used to enhance the capabilities of the plug-in.

Compiler

Compiler is an object when render-builder is executed. It provides many properties and methods to help write plug-ins.

export default class DemoWebpackPlugin extends WebpackBuilderPluginClass {
  run(compiler: Compiler, config: ChainConfig, options: PluginOptions) {
    const {
      context,
      hooks,
      log,
      buildPlugins,
      buildPresets,
      setValue,
      getValue,
    } = compiler;
  }
}

context

context saves the context information of render-buidler execution.

const {
  rootDir,
  buildConfig,
  pkg,
  commandArgs,
  command,
  appConfig,
  mockConfig,
} = context;

hooks

Use hooks to monitor the running process of render-builder.

• afterConfigLoaded: Called after the configuration file is loaded
• afterServerStarted: Called after the server is started
• afterBuild: Called after the build is completed
• failed: Called when the build fails

hooks.afterConfigLoaded.tap("afterConfigLoaded", ({ commandArgs, config }) => {
  console.log(commandArgs);
  // output  Build  configuration (webpack、vite、rollup)
  console.log(config);
});

hooks.afterServerStarted.tap(
  "afterServerStarted",
  ({
    commandArgs,
    config,
    url,
    urls = {
      lanUrlForConfig,
      lanUrlForTerminal,
      lanUrlForBrowser,
      localUrlForTerminal,
      localUrlForBrowser,
    },
  }) => {
    openBrowser(url);
  }
);

hooks.afterBuild.tap(
  "afterBuild",
  ({
    commandArgs,
    config,
    url,
    urls = {
      lanUrlForConfig,
      lanUrlForTerminal,
      lanUrlForBrowser,
      localUrlForTerminal,
      localUrlForBrowser,
    },
    compileRes,
    stats,
  }) => {}
);

hooks.failed.tap("failed", ({ error }) => {
  console.error(error);
});

setValue && getValue

class Demo1 extends WebpackBuilderPluginClass {
  run(compiler: Compiler, config: ChainConfig, options: PluginOptions) {
    const { setValu } = compiler;
    setValue("demo1", "datas");
  }
}

class Demo2 extends WebpackBuilderPluginClass {
  run(compiler: Compiler, config: ChainConfig, options: PluginOptions) {
    const { getValue } = compiler;
    const data = getValue("demo1");
    console.log(data); // datas
  }
}

config

config is a webpack-chain object

options

options are the configuration options required by the plug-in

View more plugin writing examples

Write a preset

Preset is actually a collection of plugins,For example, the following is a preset for compiling react components:

import EmitEsmCjsWebpackPlugin from "@x.render/emit-esm-cjs-webpack-plugin";
import StaticAssetsWebpackPlugin from "@x.render/static-assets-webpack-plugin";
import StyleWebpackPlugin from "@x.render/style-webpack-plugin";
import OptimizationWebpackPlugin from "@x.render/optimization-webpack-plugin";
import ReactBabelWebpackPlugin from "@x.render/react-babel-webpack-plugin";
import ReactComponentWebpackPlugin from "@x.render/react-component-webpack-plugin";

const buildReactComponentWebpackPreset = {
  install() {
    return [
      EmitEsmCjsWebpackPlugin,
      StaticAssetsWebpackPlugin,
      StyleWebpackPlugin,
      OptimizationWebpackPlugin,
      ReactBabelWebpackPlugin,
      ReactComponentWebpackPlugin,
    ];
  },
};
export * from "./types";
export default buildReactComponentWebpackPreset;

The parameters passed to preset will be passed transparently to all plug-ins. In other words, the configuration of preset is the collection of all plug-in configurations.

Configuration file

The render-builder configuration file must be configured. The render-builder will decide which plug-ins, presets, and build tools to use to run your project based on this file.

render-builder supports configuration files in multiple formats：

• build.json
• build.config.(js|ts|mjs|mts|cjs|cts)

Here are some examples of writing configuration files:

{
  "builder": "webpack",
  "plugins": [
    [ "@x.render/plugin-react-component",options]
    "@x.render/plugin-react-babel",
    "@x.render/plugin-optimization",
    "@x.render/plugin-style",
    "@x.render/plugin-static-assets",
    "@x.render/plugin-emit-esm-cjs"
  ],
  "presets": [
    "build-react-component-webpack-preset",
   [ "@x.render/build-react-component-webpack-preset",options]
  ]
}

Among them, builder selection can only be webpack, vite, rollup, which is used to tell render-builder what building tools to use to run the project.The builder selections can only be webpack, vite, and rollup, which are used to tell the render-builder what building tools to use to run the project.

• When your builder is set to webpack, your plug-in must implement WebpackBuilderPluginClass.
• When your builder is set to vite, your plug-in must implement ViteBuilderPluginClass.
• When your builder is set to rollup, your plug-in must implement RollupBuilderPluginClass.