Modern.js Builder CLI 工具使用指南

前言

Modern.js Builder 是一个现代化的前端构建工具，它提供了 Builder CLI 工具来帮助开发者快速构建非 React 项目。本文将详细介绍如何使用 Builder CLI 工具进行项目开发。

Builder CLI 简介

Builder CLI 是 Modern.js Builder 提供的命令行工具，具有以下特点：

1. 轻量级设计，只包含核心构建功能
2. 支持多种前端框架（Vue、Svelte 等）
3. 提供开发、构建、预览等基础命令
4. 支持 webpack 和 Rspack 两种构建引擎

安装与配置

安装步骤

要使用 Builder CLI，需要安装以下两个核心包：

1. @modern-js/builder-cli：CLI 工具本体
2. 构建引擎提供者（二选一）：
   • @modern-js/builder-rspack-provider（基于 Rspack）
   • @modern-js/builder-webpack-provider（基于 webpack）

推荐使用 npm 或 yarn 进行安装：

npm install @modern-js/builder-cli @modern-js/builder-rspack-provider -D

构建引擎选择

Builder CLI 支持两种构建引擎：

1. Rspack：新一代构建工具，构建速度更快
2. webpack：传统构建工具，生态更完善

开发者可以根据项目需求选择合适的构建引擎。

核心命令详解

Builder CLI 提供了三个核心命令：

1. 开发命令：builder dev

启动本地开发服务器，提供热更新等功能：

builder dev

该命令会：

• 启动开发服务器
• 启用热模块替换(HMR)
• 自动打开浏览器
• 提供错误提示和警告

2. 构建命令：builder build

构建生产环境代码：

builder build

构建结果默认输出到 dist/ 目录，包含：

• 优化后的 JavaScript 代码
• 压缩后的 CSS 文件
• 处理后的静态资源

3. 预览命令：builder serve

预览生产环境构建结果：

builder serve

注意：需要先执行 builder build 生成构建产物。

配置文件详解

Builder CLI 默认读取项目根目录下的 builder.config.ts 文件进行配置。

基本配置示例

import { defineConfig } from '@modern-js/builder-cli';

export default defineConfig({
  output: {
    disableTsChecker: true,  // 禁用 TypeScript 类型检查
  },
});

Rspack 特殊配置

使用 Rspack 时需要指定泛型类型：

import { defineConfig } from '@modern-js/builder-cli';

export default defineConfig<'rspack'>({
  // Rspack 特有配置
});

构建入口配置

Builder CLI 默认使用 src/index.(js|ts|jsx|tsx) 作为入口文件，可以通过配置修改：

import { defineConfig } from '@modern-js/builder-cli';

export default defineConfig({
  source: {
    entries: {
      main: './src/main.ts',      // 主入口
      admin: './src/admin.ts',    // 管理后台入口
    },
  },
});

插件系统

Builder CLI 支持通过插件扩展功能，例如添加 Vue 支持：

import { defineConfig } from '@modern-js/builder-cli';
import { builderPluginVue } from '@modern-js/builder-plugin-vue';

export default defineConfig({
  builderPlugins: [builderPluginVue()],
});

常用插件包括：

• Vue 支持插件
• React 支持插件
• 静态资源处理插件
• CSS 预处理插件

最佳实践

1. 项目结构建议：

   project/
   ├── src/
   │   ├── index.ts      # 主入口
   │   └── assets/       # 静态资源
   ├── builder.config.ts # 构建配置
   └── package.json
   

2. 开发流程：

   • 开发阶段使用 builder dev
   • 构建阶段使用 builder build
   • 验证阶段使用 builder serve

3. 性能优化：

   • 生产构建启用代码压缩
   • 合理配置代码分割
   • 使用 Tree Shaking 消除未使用代码

常见问题

1. 如何修改输出目录？ 在配置中设置 output.distPath 选项。

2. 如何添加环境变量？ 使用 source.define 配置项注入环境变量。

3. 如何处理静态资源？ 内置支持图片、字体等资源处理，也可通过插件扩展。

总结

Modern.js Builder CLI 为非 React 项目提供了简单高效的构建解决方案。通过本文的介绍，开发者可以快速上手使用 Builder CLI 进行项目开发和构建。其灵活的配置系统和插件机制，能够满足各种复杂项目的构建需求。