neo-widget-cli/README.md

前端脚手架：自定义组件开发工具，支持react 和 vue2.0技术栈。

## Neo 自定义组件开发工具
neo-widget-cli 是 Neo 自定义组件开发工具，基于 [AKFun](https://github.com/wibetter/akfun) 的工程能力，提供模板创建、编译构建、预览调试、多技术栈支持与一键发布。

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

### 模板类型（neo init 可选）
- **React 模板**: [react-custom-widget-template](https://github.com/wibetter/react-custom-widget-template)
- **React + TS 模板**: [react-ts-custom-widget-template](https://github.com/wibetter/react-ts-custom-widget-template)
- **Vue2 模板**: [vue2-neo-custom-widget](https://github.com/wibetter/vue2-neo-custom-widget)

## 快速开始

### 方法一：全局安装
1) 安装
```bash
yarn global add neo-widget-cli
# 或
npm i -g neo-widget-cli
```
2) 创建项目（默认 React+TS，可用 -t 指定模板，--name 指定项目名）
```bash
neo init -t=react&ts
```
3) 安装依赖并运行
```bash
# 预览自定义组件内容
npm run preview

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

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

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

### 方法二：在现有项目中使用
1) 安装到当前项目
```bash
yarn add neo-widget-cli --dev
# 或
npm i neo-widget-cli --save-dev
```
2) 在 package.json 添加脚本
```bash
"preview": "neo preview",
"linkDebug": "neo linkDebug",
"build2lib": "neo build2lib"
```
3) 初始化配置文件
```bash
neo config init
```
4) 开发调试
```bash
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) 基础规范与检查
```bash
module.exports = {
  settings: {
    enableESLint: true, // 是否开启ESLint，默认开启ESLint检测代码格式
    enableESLintFix: false, // 是否ESLint自动修正代码格式
    enableStyleLint: true, // 是否开启StyleLint，默认开启ESLint检测代码格式
    enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
  },
}
```

### 2) 构建入口（优先级：preview/linkDebug/build2lib.entry > webpack.entry）
```bash
module.exports = {
  webpack: {
    entry: { index: './src/index.js' },
  },
  preview: { entry: {} },
  linkDebug: { entry: {} },
  build2lib: { entry: {} },
}
```
备注1: 当未配置 entry 时，cli 会自动根据 src/widgets 目录自动生成 entry 配置；   
备注2: 详细配置方法请查看 Webpack 官网 ([关于entry的配置方法](https://www.webpackjs.com/configuration/entry-context/#entry))。

### 3) 解析配置（extensions/alias）
```bash
module.exports = {
  webpack: {
    resolve: {
      extensions: ['.js', '.jsx', '.vue', 'json'],
      alias: {},
    },
  },
}
```
备注1: extensions 的详细配置方法请查看Webpack官网 ([关于resolve-extensions的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-extensions))；  
备注2: alias 的详细配置方法请查看 Webpack 官网 ([关于resolve-alias的配置方法](https://www.webpackjs.com/configuration/resolve/#resolve-alias))。

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

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

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

### 7) 环境变量替换（params-replace-loader）
```bash
module.exports = {
  envParams: {
    common: { '#version#': '20250822.1' },
    local: {
      '#dataApiBase#': 'http://localhost:1024',
      '#assetsPublicPath#': 'http://localhost:1024',
      '#routeBasePath#': '/',
    },
  },
}
```

### 8) 本地开发代理与 HTTPS
```bash
module.exports = {
  preview: {
    proxyTable: {},
    https: false,
  },
}
```
备注1: [关于proxyTable的配置方法](https://www.webpackjs.com/configuration/dev-server/#devserver-proxy)；  
备注2: 启用 HTTPS 后，若浏览器提示不安全，可在 Chrome 地址栏打开 `chrome://flags/#allow-insecure-localhost` 并设置为 Enabled。

### 9) 库构建（UMD/ESM）
```bash
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
```bash
module.exports = {
  webpack: {
    moduleRules: [], // 用于添加自定义 loaders
    plugins: [], // 用于添加自定义 plugins
    babelPlugins: [  // 用于添加自定义 Babel plugins
      [
        'component',
        { libraryName: 'element-ui', styleLibraryName: 'theme-chalk' },
      ],
    ],
  },
}
```
备注: 以上自定义 babelPlugins 用于实现 [element-ui 组件按需引入](https://element.eleme.cn/#/zh-CN/component/quickstart#an-xu-yin-ru)。  

也支持以函数形式动态调整内置 Babel Plugins：  
```bash
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 不重复**
- 已按需配置对象存储参数（支持自定义）

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