Web Builder 技术方案

[anncwb]

• 开始时间: 2022-02-17
• 实施 PR: [WIP]feat(cli): cli implementation web-builder#4

描述

Web Builder 是一个由 Growing Web 提出的项目构建技术标准，它不受其它构建工具制约，不限制于vite、webpack等其它第三方构建工具，旨在抹平不同工具的差异性，由 Web Builder 内部择优选择不同的构建工具，通过读取解析工程清单project-manifest.json内所约束的标准应用格式配置，开发者只需要配置清单即可完成项目的开发、构建、发布。它支持多种构建(esm、cjs、system、·iife)格式的输出，也支持库模式(lib)、网站模式(app)两种目标的构建。

工具构建流程

Web Builder 将提供 CLI 和 Node.js API 两种使用方式，以下为构建工具整体流程

             Start
               ▼
        ┌──────┴──────┐
        │ Web Builder │
        └──────┬──────┘
               ▼
  ┌────────────┴────────────┐
  │     Project Manifest    │
  │ (project-manifest.json) │
  └────────────┬────────────┘
               ▼
   ┌───────────┴───────────┐
   │ Web Builder Container │
   │ (Vite, Webpack, ...)  │
   └───────────┬───────────┘
               ▼
       ┌───────┴──•••──┐
┌──────┴──────┐ ┌──────┴───────────────┐
│ Application │ │ Application Manifest │
└──────┬──────┘ │   (web-widget.json)  │
       │        └──────┬───────────────┘
       └───────┬───────┘
               ▼
              End

动机

统一的构建工具与模板代码能缓解项目之间各自为政的问题，但随着时间的推移，构建配置与模板代码将会被项目同化。当企业项目数量变多或规模变大的时候，原来运作良好的部分都会变得糟糕，而工程的复杂度却阻碍了基础设施的升级，这样的问题在不同的企业、不同的团队反复发生，因此我们希望将最基础的部分从业务工程中抽离出来，建设成高可用的解决方案，借机建立必要的约束以维持长久的稳定。

基本示例

前置配置

// project-minifest.json
{
  "schemaVersion": "1.0.0",
  "entry": "src/main.ts"
}

// package.json
{
  "name": "playground-vue3",
  "version": "1.0.0",
  "scripts": {
    "dev": "web-builder dev",
    "build": "web-builder build"
  },
  "dependencies": {
    "vue": "^3.2.31"
  },
  "devDependencies": {
    "@growing-web/web-builder": "workspace:*",
    "@vue/compiler-sfc": "3.2.31"
  }
}

运行

npm run dev
npm run build

直接运行 npm run dev 即可运行项目，无需配置相关参数，工具会自动择优选择vite、webpack其中的一个进行启动（目前只支持 vite）,并根据项目类型（支持vue2、vue3、react、lit、preact、vanilla）进行启动

详细设计

CLI 命令设计

CLI 命令包含 dev、build两个命令，其余命令暂不支持，可做后续扩展，这里暂不讨论

dev

基本命令为：web-builder dev

命令行参数：

• --mode 指定环境模式
• --open 在服务器启动时打开浏览器
• --https 指定是否启用 https
• --mkcert 在服务器启动时创建证书证书

build

基本命令为：web-builder build

命令行参数：

• --mode 指定环境模式
• --no-clean 在构建项目之前不要删除 dist 目录
• --report 生成 report.html 以帮助分析捆绑内容
• --report-json 生成 report.json 以帮助分析捆绑内容
• --sourcemap 构建项目后生成map文件
• --watch 实时监听变化并构建

清单加载

工程清单加载见：工程清单技术标准

配置文件加载

配置文件与工程清单的区别在于，工程清单 用于指定工程构建必须的配置，配置清单用于配置开发体验、非必需配置相关的内容以及插件引入。

配置文件支持以下4种格式：

• web-builder.config.ts
• web-builder.config.mjs

export interface UserConfig {
  server?: {
    /**
     * 在服务器启动时打开浏览器
     * @default false
     */
    open?: boolean

    /**
     * 指定是否启用 https
     * @default false
     */
    https?: boolean

    /**
     * 在服务器启动时创建证书证书
     *https = true 时生效
     * @default true
     */
    mkcert?: boolean
  }

  build?: {
    /**
     * 在构建项目之前删除 dist 目录
     * @default true
     */
    clean?: boolean

    /**
     * 生成 report.html 以帮助分析捆绑内容
     * @default false
     */
    report?: boolean

    /**
     * 生成 report.json 以帮助分析捆绑内容
     * @default false
     */
    reportJson?: boolean

    /**
     * 构建项目后生成`map`文件
     * @default false
     */
    sourcemap?: boolean

    /**
     * 实时监听变化并构建
     * @default false
     */
    watch?: boolean
  }

  /**
   * user plugins
   */
  plugins?: Plugins[]
}

Alias 内置

默认内置了 ~ 别名，其余 Alias 配置暂不允许配置，防止过多的别名带来了更多的认知成本

 alias: {
        '~': `${path.resolve(rootDir, 'src')}/`,
},

Bundler 模块

Bundler 模块用于提供多种构建器，方便进行切换，每个构建器为一个npm子包，通过所设置的bundlerType 加载器类型，由lodaer加载器进行加载：

import type {
  WebBuilder,
  WebBuilderStats,
} from '@growing-web/web-builder-types'
import type { ViteDevServer } from 'vite'
import { WEB_BUILDER_HOOK } from '@growing-web/web-builder-constants'

type BundlerResult =
  | typeof import('@growing-web/web-builder-bundler-vite')
  | typeof import('@growing-web/web-builder-bundler-webpack')

export async function loadBundler(webBuilder: WebBuilder): Promise<{
  build: (() => Promise<WebBuilderStats>) | (() => Promise<void>)
  dev: (() => Promise<ViteDevServer>) | (() => Promise<void>)
}> {
  const useVite = webBuilder.service?.bundlerType === 'vite'

  const { buildBundler, devBundler }: BundlerResult = await (useVite
    ? import('@growing-web/web-builder-bundler-vite')
    : import('@growing-web/web-builder-bundler-webpack'))
  try {
    return {
      build: buildBundler(webBuilder),
      dev: devBundler(webBuilder),
    }
  } catch (error) {
    await webBuilder.callHook(WEB_BUILDER_HOOK.BUILD_ERROR, error)
    throw error
  }
}

插件模块

WIP

待讨论的问题

• 清单于配置文件的界限不是很明确，可能会导致使用困扰

参考

• nuxt3
• umijs
• icejs
• vite