@kbeaver/cli-command-build NPM

`@kbeaver/cli-command-build`

Usage

命令需要项目已配置 kb.json 里的 build 属性

# 在项目kb项目根目录下直接运行命令
# 需要在 kb.json 文件里配置 build
# 如果配置里配置了多个任务，可输入任务名称执行对应的任务
$ kb build [taskName]

build 配置

kb.json

schema : https://config.kbeaver.cn/files/kb.schema.json

{
  // 编译任务配置
  "build": [
    {
      "name": "任务名称",
      "text": "命令行提示信息",
      "tasks": [...],
    }
  ]
}

build 里可配置两种任务，一种是 Task ，一种是预设任务

type BuildConfig = (Task | string)[]

预设任务

预设是预先编辑好的配置，已经保存在 build 命令里，直接指定即可。

可使用预置任务：

buildComponent 针对 UI 和 Plus 组件库预先设置好的打包配置
... 待开发

使用：

{
  "build": ["buildComponent"]
}

指定某些任务进行扩展配置(merge)

{
  "build": [
    {
      "name": "buildComponent",
      "extend": {
        "BuildIIFEScript": {
          "options": {
            "buildGlobalName": "KbUiPlus"
          }
        }
      }
    }
  ]
}

Task

任务会顺序执行，每个任务里的子任务根据配置可并行或顺序执行。

// 子任务
type ChildTask =
  | ScriptTask
  | StyleTask
  | FileTask
  | CustomizeTask
  | DeclarationTask

interface Task {
  // 任务名称（key），唯一
  name: string
  // 任务执行时输出的文本
  text: string
  // 子任务列表
  tasks: ChildTask[]
  // 设定执行顺序
  // 可设置值：series，parallel
  // 默认安顺序执行 series
  order?: 'series' | 'parallel'
  // options?:
  extend?: {
    [key: string]: ChildTask
  }
}

子任务一共有五种类型：

Script build 任务
Style build 任务
文件操作任务
自定义任务
生成 Typescript 类型声明文件任务

Task Base & Child Task Base Options

interface ChildTaskBase {
  name?: string
  // 任务类型
  type: 'script' | 'style' | 'file' | 'customize' | 'declaration'
  // 文件地址（glob 匹配）
  // eg: '**/*/*.{ts,tsx}'
  src: string
  options: TaskOptionsBase
}

interface TaskOptionsBase {
  // 匹配控制
  // 默认跟路径，设置此项后。匹配出的文件路径，不包含此路径。默认空
  srcBase?: string
  // 匹配点开头的文件，默认false
  globDot?: boolean
  // 忽略匹配模式，可以多个。从src匹配模式里排除。默认空
  // 忽略demo和tests目录: ['**/demo/', '**/tests/']
  globIgnore?: string[]
  globNoDir?: boolean
  // 是否输出绝对路径，默认false
  globAbsolute?: boolean
  // 指定输出路径（相对于项目根目录，kb.json 同级)
  outDir: string
}

所有路径均是相对于项目根目录

ScriptTask

使用 esbuild 对 ts、tsx 或 js 进行编译和捆绑打包，

类型：

interface ScriptTask {
  type: 'script'
  // 文件地址（glob 匹配）
  src: string
  options: ScriptTaskOptions
}

interface ScriptTaskOptions extends TaskOptionsBase {
  // esbuild 设置
  // 是否开启 bundle， 默认 false
  buildBundle?: boolean
  // 设定全局变量
  buildDefine?: Record<string, string>
  // 入口点
  buildEntryPoints?: Record<string, string> | string[]
  // 外部：指定那些模块不打包
  buildExternal?: string[]
  // 编译目标，默认 esm
  buildFormat?: 'iife' | 'cjs' | 'esm'
  // 注入代码，code path
  buildInject?: string[]
  // 为指定的文件类型配置加载程序
  // 加载起类型 https://esbuild.github.io/content-types/
  // eg: { '.png': 'file' }
  buildLoader?: {
    [ext: string]: ESBuild.Loader
  }
  // 是否压缩，默认false
  // process.env.NODE_ENV = production 自动启用
  buildMinify?: boolean
  // 单文件入口时，指定输出文件
  buildOutFile?: string
  // 目标平台，默认 browser
  buildPlatform?: 'browser' | 'node' | 'neutral'
  // 源码地图
  buildSourcemap?: boolean | 'linked' | 'external' | 'inline' | 'both'
  // 可设置选项查看：https://esbuild.github.io/api/#target
  buildTarget?: string | string[]

  /**
   * 高级选项
   */
  // 是否覆盖原代码，outDir 设置为 '.'
  buildAllowOverwrite?: boolean
  // 是否开启打包代码分析
  // 必须同时开启 buildBundle、metafile
  buildAnalyze?: boolean
  // 指定资产的资产名称模板，需配合 buildLoader 使用
  // eg: assets/[name]-[hash]
  buildAssetNames?: string
  buildEntryNames?: string
  // 多入口时，指定输出文件的扩展名
  buildOutExtension?: Record<string, string>
  // 剪枝，buildBundle = true, buildFormat = esm 或 iife 时生效
  buildTreeShaking?: boolean
  /*
   * 其它
   */
  // plugins
  buildPlugins?: ScriptBuildPlugin
}

例子：

  {
    name: 'buildScript',
    text: 'Build Script',
    tasks: [
      {
        type: 'script',
        src: '**/*.{ts,tsx}',
        options: {
          srcBase: 'src/components',
          globIgnore: ['**/{demo,tests}/*'],
          outDir: 'es',
          buildFormat: 'esm',
          buildMinify: true,
          buildEntryNames: '[dir]/[name]',
          buildPlugins: [''],
        },
      },
    ],
  },

StyleTask

类型描述：

interface StyleTask {
  type: 'style'
  src: string
  options: StyleTaskOptions
}

interface StyleTaskOptions extends TaskOptionsBase {
  // 输出路径
  outDir: string
  // 出书文件名称
  fileName?: string
  // 输出文件的扩展名
  ext?: string
  // postcss config
  // 是否开启压缩，默认 false
  minify?: boolean
  // cssModules 设置
  cssModules?: CssModules
  // assets image inliner
  // 静态资源匹配地址，可以使用 glob 匹配模式
  // 这里的地址是相对以css里地址相对地址
  assetPaths?: string[]
  // 小于此阈值的导入或引用资源将内联为 base64 编码，以避免额外的 http 请求。设置为 0 可以完全禁用此项
  // 默认 4096 (4kb)
  assetInlineLimit?: number
  // process options 设置，详细设置看官网
  postcssOptions?: ProcessOptions
  event?: StyleTaskOptionsEvent
}

interface CssModules {
  exportClasses?: {
    // 输出路径，默认和src 文件路径一致
    outPath?: string
    // 文件名称，默认和src css 文件同名
    fileName?: string
    // 默认 json 后缀
    ext?: string
  }
  // 是否使用 vite 或 webpack 里的 cssModules 的配置，默认空
  // 设置此项后，exportClasses 无效
  loadOptions?: 'vite' | 'webpack'
  // postcss-modules 插件的 options 设置
  options?: PostcssModulesOptions
}

interface StyleTaskOptionsEvent {
  onBeforeTransform?: (code: string) => string
  onAfterTransform?: (code: string) => void
}

// 具体设置查看官网说明
interface PostcssModulesOptions {
  // css module 映射 json 的后续处理设置
  getJSON?(
    cssFilename: string,
    json: Record<string, string>,
    outputFilename?: string
  ): void

  localsConvention?:
    | 'camelCase'
    | 'camelCaseOnly'
    | 'dashes'
    | 'dashesOnly'
    | ((
        originalClassName: string,
        generatedClassName: string,
        inputFile: string
      ) => string)

  scopeBehaviour?: 'global' | 'local'
  globalModulePaths?: RegExp[]

  generateScopedName?:
    | string
    | ((name: string, filename: string, css: string) => string)

  hashPrefix?: string
  exportGlobals?: boolean
  root?: string

  resolve?: (file: string) => string | Promise<string>
}

DeclarationTask

使用 tsc 生成类型声明。

项目必须安装 typescript，否则会报错。
必须指定一个 tsconfig 配置的路径

类型描述：

interface DeclarationTask {
  type: 'declaration'
  // 指定 tsconfig 配置的路径
  tsconfigPath: string
}

FileTask

对匹配到的文件进行对应文件操作，拷贝、删除、移动、清理目录。

由于 options 里的 outDir 是必选项目，在删除和清理目录动作时，设置为空字符即可

类型描述：

interface FileTask {
  type: 'file'
  src: string
  options: FileTaskOptions
}

interface FileTaskOptions extends TaskOptionsBase {
  // 需要执行的动作
  action: 'copy' | 'remove' | 'move' | 'clean'
}

CustomizeTask

自定义任务。

可以在 options 里的 execQueue 属性里设置需要运行的异步方法，或 js 文件的地址（路径相对项目根目录）执行器会载入对应的文件运行。

js 文件必须使用 es6 的默认导出。
自定义异步方法，接受固定的参数
执行器会把上一个执行完方法返回的结果传给下一个方法。

类型描述：

interface CustomizeTask {
  type: 'customize'
  src: string
  options: CustomizeTaskOptions
}

interface CustomizeTaskOptions extends TaskOptionsBase {
  /**
   * execQueue 执行队列:
   * (function ｜ string)[]
   * - function 必须是一个异步函数，async 或者 promise
   * - string 文件路径地址
   */
  execQueue: (CustomizeFunction | string)[]
}

interface CustomizeFunctionOptions {
  // 自定义任务匹配到的文件或文件夹路径列表
  src: string[]
  // 输出路径，也就是 outDir 里的设置
  dest: string
  srcBase?: string
  // 项目根目录
  rootPath: string
  // 上一个自定义方法返回的结果
  results?: any
}
type CustomizeFunction = (data: CustomizeFunctionOptions) => Promise<any>