neo-cmp-cli 1.0.0

package/README.md

@@ -0,0 +1,236 @@
+## Neo 自定义组件开发工具
+neo-cmp-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-cmp-cli
+# 或
+npm i -g neo-cmp-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-cmp-cli --dev
+# 或
+npm i neo-cmp-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-cmp-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/components 目录自动生成 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 不重复**
+- 已按需配置对象存储参数（支持自定义）
+
+---
+如需更多细节与高级用法，请参考模板项目与源码注释。

package/bin/neo.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/module/index');

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "neo-cmp-cli",
+  "version": "1.0.0",
+  "description": "前端脚手架：自定义组件开发工具，支持react 和 vue2.0技术栈。",
+  "keywords": [
+    "neo-cli",
+    "自定义组件开发工具"
+  ],
+  "author": "wibetter",
+  "license": "MIT",
+  "bin": {
+    "neo": "./bin/neo.js"
+  },
+  "main": "src/module/main.js",
+  "scripts": {
+    "neo": "neo",
+    "dev": "node ./test/demo.js",
+    "format": "prettier --write \"src/**/**/*.{js,jsx,vue,tsx,ts,scss,less,json}\""
+  },
+  "files": [
+    "bin/*",
+    "src/*",
+    "test/*"
+  ],
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "lint-staged": {
+    "src/**/**/*.{js,jsx,ts,tsx,vue,css,less,scss,json}": [
+      "prettier --write"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://git@github.com:wibetter/neo-cmp-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wibetter/neo-cmp-cli/issues"
+  },
+  "dependencies": {
+    "akfun": "^5.1.10",
+    "chalk": "^4.0.0",
+    "deepmerge": "^4.2.2",
+    "figlet": "^1.2.0",
+    "fs-extra": "^10.1.0",
+    "inquirer": "^7.3.3",
+    "ora": "^4.0.4",
+    "webpack-sources": "^3.2.3",
+    "yargs": "^12.0.2",
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^8.3.5",
+    "@commitlint/config-conventional": "^9.1.1",
+    "husky": "^4.2.5",
+    "lint-staged": "^10.2.9",
+    "prettier": "^2.0.5"
+  },
+  "engines": {
+    "node": ">= 10.13.0",
+    "npm": ">= 6.4.1"
+  },
+  "browserslist": [
+    "> 1%",
+    "last 2 versions",
+    "not ie <= 8",
+    "iOS >= 8",
+    "Firefox >= 20",
+    "Android > 4.4"
+  ]
+}

package/src/config/default.config.js

@@ -0,0 +1,136 @@
+'use strict';
+// 统一路径解析：
+const { resolve } = require('akfun');
+const path = require('path'); // 以命令执行目录为根目录
+
+// 当前neo的路径解析（用于获取neo-cmp-cli本身的文件地址）
+function resolveByDirname(dir) {
+  return path.resolve(__dirname, dir);
+}
+
+/**
+ * 脚手架赋予当前项目的默认配置
+ */
+const defaultNEOConfig = {
+  settings: {
+    enableESLint: false, // 是否开启ESLint，默认开启ESLint检测代码格式
+    enableESLintFix: false, // 是否ESLint自动修正代码格式
+    enableStyleLint: false, // 是否开启StyleLint，默认开启ESLint检测代码格式
+    enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
+  },
+  webpack: {
+    resolve: {
+      // webpack的resolve配置
+      extensions: ['.js', '.jsx', '.ts', '.tsx', '.vue', '.min.js', '.json'], // 用于配置webpack在尝试过程中用到的后缀列表
+      alias: {
+        '@': resolve('src')
+      }
+    },
+    createDeclaration: false, // 打包时是否创建ts声明文件
+    ignoreNodeModules: false, // 打包时是否忽略 node_modules
+    allowList: [], // ignoreNodeModules为true时生效
+    externals: [], // 从输出的 bundle 中排除依赖
+    projectDir: ['src'],
+    template: resolveByDirname('../initData/defaultTemplate.html'), // 默认使用neo-widget提供的页面模板（会启动页面设计器）
+    sassResources: []
+  },
+  envParams: {
+    // 项目系统环境变量
+    common: {
+      // 通用参数
+      '#version#': '20221229.1'
+    },
+    local: {
+      // 本地开发环境
+      '#dataApiBase#': 'http://localhost:1024', // 数据接口根地址
+      '#assetsPublicPath#': 'http://localhost:1024', // 静态资源根地址
+      '#routeBasePath#': '/' // 路由根地址
+    },
+    online: {
+      // 线上正式环境配置参数
+      '#dataApiBase#': '/', // 数据接口根地址 "//xxx.cn/"格式
+      '#assetsPublicPath#': '', // 静态资源根地址 "//xxx.cn/_spa/projectName"格式
+      '#routeBasePath#': '/' // 路由根地址 "/_spa/projectName/"格式
+    }
+  },
+  dev: {
+    // 用于开启本地调试模式的相关配置信息
+    NODE_ENV: 'development',
+    port: 80, // 设置基础端口，如果被占用则自动寻找可用端口
+    autoOpenBrowser: true,
+    assetsPublicPath: '/', // 设置静态资源的引用路径（根域名+路径）
+    assetsSubDirectory: '',
+    hostname: 'localhost',
+    proxyTable: {},
+    /** CSS Sourcemaps off by default because relative paths are "buggy"
+     * with this option, according to the CSS-Loader README
+     * (https://github.com/webpack/css-loader#sourcemaps)
+     * In our experience, they generally work as expected,
+     * just be aware of this issue when enabling this option.
+     */
+    cssSourceMap: true
+  },
+  build: {
+    // 用于构建生产环境代码的相关配置信息
+    NODE_ENV: 'production', // production 模式，会启动UglifyJsPlugin服务
+    assetsRoot: resolve('dist'), // 编译完成的文件存放路径
+    assetsPublicPath: '/', // 设置静态资源的引用路径（根域名+路径）
+    assetsSubDirectory: '', // 资源引用二级路径
+    productionSourceMap: false,
+    // closeHtmlWebpackPlugin: true, // 可用于控制不生成html文件
+    // Gzip off by default as many popular public hosts such as
+    // Surge or Netlify already gzip all public assets for you.
+    // Before setting to `true`, make sure to:
+    // npm install --save-dev compression-webpack-plugin
+    productionGzip: false,
+    productionGzipExtensions: ['js', 'css', 'json'],
+    // Run the build command with an extra argument to
+    // View the bundle analyzer report after build finishes:
+    // `npm run build --report`
+    // Set to `true` or `false` to always turn it on or off
+    bundleAnalyzerReport: false
+  },
+  build2lib: {
+    // 用于构建第三方功能包的配置文件
+    NODE_ENV: 'production',
+    libraryName: '', // 构建第三方功能包时最后导出的引用变量名
+    assetsRoot: resolve('dist'), // 编译完成的文件存放路径
+    assetsPublicPath: '/', // 设置静态资源的引用路径（根域名+路径）
+    assetsSubDirectory: '', // 资源引用二级路径
+    productionSourceMap: false,
+    productionGzip: false,
+    productionGzipExtensions: ['js', 'css', 'json'],
+    bundleAnalyzerReport: false
+  },
+  linkDebug: {
+    // 用于开启本地调试模式的相关配置信息
+    NODE_ENV: 'development',
+    closeHtmlWebpackPlugin: true,
+    autoOpenBrowser: false,
+    cssExtract: false,
+    consoleInfo: '当前自定义组件可用外链地址'
+  },
+  publish2oss: {
+    output: {
+      filename: '[name].js',
+      library: {
+        type: 'var', // webpack 5 中生成 IIFE 格式的 type 配置
+        export: 'default'
+      },
+      globalObject: 'this' // 定义全局变量,兼容node和浏览器运行，避免出现"window is not defined"的情况
+    },
+    cssExtract: false, // 不额外提取css文件
+    ossType: 'ali', // oss类型：ali、baidu
+    ossConfig: {
+      endpoint: 'https://oss-cn-beijing.aliyuncs.com',
+      // 个人阿里云子账户（neo-cmp-cli），有流量限制，请勿滥用
+      AccessKeyId: 'LTAI5tS47y9L4fAPLXNoEzxS',
+      AccessKeySecret: '8qz2GxxJJe44K5NRmLAAzIVJnbcYAU',
+      bucket: 'neo-widgets' // 存储桶名称
+    },
+    assetsRoot: resolve('dist') // 上传指定目录下的脚本文件
+  }
+};
+
+// 备注：数组类型则直接覆盖
+module.exports = defaultNEOConfig;

package/src/config/index.js

@@ -0,0 +1,9 @@
+// 统一路径解析：
+const { resolve, getConfigObj, deepMergeConfig } = require('akfun');
+const defaultNEOConfig = require('./default.config');
+
+// 从项目根目录获取当前项目的配置文件
+const curProjectConfig = getConfigObj(resolve('neo.config.js'));
+
+// 备注：数组类型则直接覆盖
+module.exports = deepMergeConfig(defaultNEOConfig, curProjectConfig);

package/src/initData/defaultTemplate.html

@@ -0,0 +1,13 @@
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="format-detection" content="telephone=no"/>
+  <meta name="viewport" content="initial-scale=1.0,user-scalable=no,width=device-width,viewport-fit=cover">
+  <meta http-equiv="X-UA-Compatible" content="ie=edge">
+  <title>neo-widget Demo</title>
+</head>
+<body>
+<div id="root"></div>
+</body>
+</html>

package/src/initData/neo.config.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const path = require('path');
+
+// 统一路径解析
+function resolve(dir) {
+  return path.resolve(__dirname, dir);
+}
+
+// 包括生产和开发的环境配置信息
+module.exports = {
+  settings: {
+    enableESLint: false, // 调试模式是否开启ESLint，默认关闭ESLint检测代码格式
+    enableESLintFix: false, // 是否自动修正代码格式，默认不自动修正
+    enableStyleLint: false, // 是否开启StyleLint，默认开启ESLint检测代码格式
+    enableStyleLintFix: false // 是否需要StyleLint自动修正代码格式
+  },
+  webpack: {
+    entry: {
+      // webpack构建入口（优先级低于于dev、build和build2lib中的entry配置）
+      index: './src/index.js'
+    },
+    resolve: {
+      // webpack的resolve配置
+      extensions: ['.js', '.jsx', '.ts', '.tsx', '.vue', '.min.js', 'json'], // 用于配置webpack在尝试过程中用到的后缀列表
+      alias: {
+        '@': resolve('src')
+      }
+    },
+    createDeclaration: false, // 打包时是否创建ts声明文件
+    ignoreNodeModules: false, // 打包时是否忽略 node_modules
+    allowList: [], // ignoreNodeModules为true时生效
+    externals: [], // 从输出的 bundle 中排除依赖
+    projectDir: ['src'],
+    sassResources: []
+  },
+  envParams: {
+    // 项目系统环境变量
+    common: {
+      // 通用参数
+      '#version#': '20200810.1'
+    },
+    local: {
+      // 本地开发环境
+      '#dataApiBase#': 'http://localhost:1024', // 数据接口根地址
+      '#assetsPublicPath#': 'http://localhost:1024', // 静态资源根地址
+      '#routeBasePath#': '/' // 路由根地址
+    },
+    online: {
+      // 线上正式环境配置参数
+      '#dataApiBase#': '/', // 数据接口根地址 "//xxx.cn/"格式
+      '#assetsPublicPath#': '', // 静态资源根地址 "//xxx.cn/_spa/projectName"格式
+      '#routeBasePath#': '/' // 路由根地址 "/_spa/projectName/"格式
+    }
+  },
+  build: {
+    entry: {
+      index: './src/index.js'
+    },
+    // 用于构建生产环境代码的相关配置信息
+    NODE_ENV: 'production', // production 模式，会启动UglifyJsPlugin服务
+    assetsRoot: resolve('dist'), // 编译完成的文件存放路径
+    assetsPublicPath: '/', // 设置静态资源的引用路径（根域名+路径）
+    assetsSubDirectory: '', // 资源引用二级路径
+    productionSourceMap: false,
+    // Gzip off by default as many popular public hosts such as
+    // Surge or Netlify already gzip all public assets for you.
+    // Before setting to `true`, make sure to:
+    // npm install --save-dev compression-webpack-plugin
+    productionGzip: false,
+    productionGzipExtensions: ['js', 'css', 'json'],
+    // Run the build command with an extra argument to
+    // View the bundle analyzer report after build finishes:
+    // `npm run build --report`
+    // Set to `true` or `false` to always turn it on or off
+    bundleAnalyzerReport: false
+  },
+  build2lib: {
+    entry: {
+      index: './src/index.js'
+    },
+    // 用于构建第三方功能包的配置文件
+    NODE_ENV: 'production',
+    libraryName: '', // 构建第三方功能包时最后导出的引用变量名
+    assetsRoot: resolve('dist'), // 编译完成的文件存放路径
+    assetsPublicPath: '/', // 设置静态资源的引用路径（根域名+路径）
+    assetsSubDirectory: '', // 资源引用二级路径
+    ignoreNodeModules: true, // 打包时是否忽略 node_modules
+    allowList: [], // ignoreNodeModules为true时生效
+    productionSourceMap: false,
+    productionGzip: false,
+    productionGzipExtensions: ['js', 'css', 'json'],
+    bundleAnalyzerReport: false
+  },
+  build2esm: {
+    input: resolve('src/main.js'),
+    fileName: 'index'
+  }
+};