Neo 自定义组件开发工具

neo-widget-cli 是 Neo 自定义组件开发工具，基于 AKFun 的工程能力，提供模板创建、编译构建、预览调试、多技术栈支持与一键发布。

主要特性

• 零配置: 内置默认配置，开箱可用；
• 多技术栈: 支持 Vue2、React、React+TypeScript 自定义组件的调试、构建与发布；
• 多构建场景: 本地预览（含热更新/代理）、外链调试、库构建（UMD/ESM）；
• 灵活可配: 支持 构建入口、别名、代理、SASS 注入、ESLint/StyleLint、Babel/Loader/Plugin 扩展等配置；
• 样式与规范: 内置 Autoprefixer、Sass、PostCSS、ESLint、StyleLint；
• 参数替换: 支持基于 params-replace-loader 的环境变量批量替换；
• 一键发布: 内置发布到 OSS 的能力，支持自定义对象存储配置。

模板类型（neo init 可选）

• React 模板: react-custom-widget-template
• React + TS 模板: react-ts-custom-widget-template
• Vue2 模板: vue2-neo-custom-widget

快速开始

方法一：全局安装

1. 安装

yarn global add neo-widget-cli
# 或
npm i -g neo-widget-cli

2. 创建项目（默认 React+TS，可用 -t 指定模板，--name 指定项目名）

neo init -t=react&ts

3. 安装依赖并运行

# 预览自定义组件内容
npm run preview

# 外链调试（在平台线上预览与调试）
npm run linkDebug

# 构建库产物（默认输出到 dist）
npm run build2lib

# 构建并发布到 OSS（确保 package.json 的 name 唯一、version 不重复）
npm run publish2oss

方法二：在现有项目中使用

1. 安装到当前项目

yarn add neo-widget-cli --dev
# 或
npm i neo-widget-cli --save-dev

2. 在 package.json 添加脚本

"preview": "neo preview",
"linkDebug": "neo linkDebug",
"build2lib": "neo build2lib"

3. 初始化配置文件

neo config init

4. 开发调试

npm run preview
npm run linkDebug
npm run build2lib

常用命令

• neo init: 交互式创建项目（支持 -t、--name）。
• neo preview: 本地预览自定义组件内容，默认支持热更新与接口代理。
• neo linkDebug: 外链调试模式，在平台端页面设计器中联调组件。
• neo build2lib: 产出 UMD/ESM 库文件（可配置）。
• neo publish2oss: 构建并上传到对象存储（可自定义配置）。

配置说明（neo.config.js）

neo-widget-cli 默认提供完整配置；如需自定义，使用 neo config init 生成 neo.config.js 并按需修改。 以下为常用配置示例（片段可自由组合）。

1) 基础规范与检查

module.exports = {
  settings: {
    enableESLint: true, // 是否开启ESLint，默认开启ESLint检测代码格式
    enableESLintFix: false, // 是否ESLint自动修正代码格式
    enableStyleLint: true, // 是否开启StyleLint，默认开启ESLint检测代码格式
    enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
  },
}

2) 构建入口（优先级：preview/linkDebug/build2lib.entry > webpack.entry）

module.exports = {
  webpack: {
    entry: { index: './src/index.js' },
  },
  preview: { entry: {} },
  linkDebug: { entry: {} },
  build2lib: { entry: {} },
}

备注1: 当未配置 entry 时，cli 会自动根据 src/widgets 目录自动生成 entry 配置；
备注2: 详细配置方法请查看 Webpack 官网 (关于entry的配置方法)。

3) 解析配置（extensions/alias）

module.exports = {
  webpack: {
    resolve: {
      extensions: ['.js', '.jsx', '.vue', 'json'],
      alias: {},
    },
  },
}

备注1: extensions 的详细配置方法请查看Webpack官网 (关于resolve-extensions的配置方法)；
备注2: alias 的详细配置方法请查看 Webpack 官网 (关于resolve-alias的配置方法)。

4) 页面模板与样式资源

module.exports = {
  webpack: {
    template: '', // 自定义页面模板路径
    sassResources: [], // sassResources 中添加的 样式文件会作为项目的公共SASS内容（变量、mixin、function等）
  },
}

5) 依赖打包策略（忽略 node_modules）

module.exports = {
  webpack: {
    ignoreNodeModules: true, // 打包时是否忽略 node_modules，默认为false
    allowList: [], // 用于配置会注入bundle中的依赖包（ignoreNodeModules 为 true 时生效）
  },
}

6) TypeScript 声明文件与工程目录

module.exports = {
  webpack: {
    createDeclaration: false, // 可选择是否生成ts声明文件，默认为false
    projectDir: ['./src'], // 构建项目中，设置生效的目录（可同时设置多个目录），用于提高前端工程执行效率。可以不配置，默认为['./src']
  },
}

7) 环境变量替换（params-replace-loader）

module.exports = {
  envParams: {
    common: { '#version#': '20250822.1' },
    local: {
      '#dataApiBase#': 'http://localhost:1024',
      '#assetsPublicPath#': 'http://localhost:1024',
      '#routeBasePath#': '/',
    },
  },
}

8) 本地开发代理与 HTTPS

module.exports = {
  preview: {
    proxyTable: {},
    https: false,
  },
}

备注1: 关于proxyTable的配置方法；
备注2: 启用 HTTPS 后，若浏览器提示不安全，可在 Chrome 地址栏打开 chrome://flags/#allow-insecure-localhost 并设置为 Enabled。

9) 库构建（UMD/ESM）

module.exports = {
  build2lib: {
    NODE_ENV: 'production',
    libraryName: '',
    assetsRoot: resolve('dist'),
    assetsPublicPath: '/',
    assetsSubDirectory: '',
    productionSourceMap: false,
    productionGzip: false,
    productionGzipExtensions: ['js', 'css', 'json'],
    bundleAnalyzerReport: false,
    ignoreNodeModules: true,
    allowList: [],
  },
}

10) 自定义 Loader / Plugin / Babel Plugins

module.exports = {
  webpack: {
    moduleRules: [], // 用于添加自定义 loaders
    plugins: [], // 用于添加自定义 plugins
    babelPlugins: [  // 用于添加自定义 Babel plugins
      [
        'component',
        { libraryName: 'element-ui', styleLibraryName: 'theme-chalk' },
      ],
    ],
  },
}

备注: 以上自定义 babelPlugins 用于实现 element-ui 组件按需引入。

也支持以函数形式动态调整内置 Babel Plugins：

module.exports = {
  webpack: {
    babelPlugins: (curBabelPlugins) => {
      curBabelPlugins.push(/* your plugin */)
      return curBabelPlugins
    },
  },
}

多页面与模板

• 多页面入口: 当 entry 仅配置一个且对应文件不存在时，会自动从 src/pages 扫描以 .ts/.tsx/.js/.jsx 结尾的文件作为入口，匹配同名 HTML 作为模板。
• 模板选择: 优先使用 ./src/index.html；不存在时使用内置默认模板。多页面时若存在同名 HTML，将其作为页面模板。

发布到对象存储（OSS）

执行 npm run publish2oss 即可构建并上传到对象存储。发布前请确保：

• package.json 的 name 唯一
• version 不重复
• 已按需配置对象存储参数（支持自定义）

如需更多细节与高级用法，请参考模板项目与源码注释。