@snack-kit/scripts

@snack-kit/scripts

Snack 模块打包脚手架，提供开发调试、生产打包、独立入口页面打包等命令。

安装

npm install @snack-kit/scripts --save-dev

命令

snack-cli — 全局脚手架

全局安装后使用，用于初始化工程和创建模块。

命令	说明
snack-cli init [dir]	初始化新 snack 工程
snack-cli create	在当前工程创建新模块模版
snack-cli -v	查看当前版本号

snack-scripts — 项目构建

安装到项目 devDependencies 后通过 npm run 调用，用于开发调试和生产打包。

命令	说明
snack-scripts start	启动开发调试服务
snack-scripts build	生产模式打包
snack-scripts entry	打包独立入口页面

init — 初始化工程

# 在当前目录初始化
snack-cli init

# 在指定目录初始化
snack-cli init my-project

交互式提问：项目名、描述、作者、调试服务地址、入口页面 id/type、React 版本（17 / 18 / 19）。

提示语言跟随系统语言自动切换（中文 / English）。

生成文件：

my-project/
├── package.json
├── tsconfig.json
├── .gitignore
└── src/
    ├── env.d.ts
    └── package/       ← 模块目录

create — 创建模块

在 snack 工程根目录执行：

snack-cli create

交互式提问：模块名称、目录名（PascalCase）、描述、作者、是否生成 setting 模块。

生成文件（以 UserManager 为例）：

src/package/UserManager/
├── snack.json
├── index.ts
└── src/
    ├── index.tsx       ← 继承 Snack 基类
    ├── setting.tsx     ← 继承 SnackSetting 基类（可选）
    └── style/
        ├── index.scss
        └── setting.scss

初始化生成的 package.json scripts：

{
  "scripts": {
    "start": "snack-scripts start",
    "build": "snack-scripts build",
    "entry": "snack-scripts entry"
  },
  "devDependencies": {
    "@snack-kit/scripts": "^0.4.0"
  }
}

package.json 配置项

{
  "input": "./src/package",
  "output": "./dist",
  "snack": {
    "externals": {},
    "buildIgnore": [],
    "devPackage": [],
    "entry": {
      "name": "entry",
      "id": "my_page",
      "type": "portal",
      "title": "My App",
      "favicon": "./favicon.ico",
      "service": "",
      "devServer": "",
      "mobile": {
        "id": "my_page_mobile",
        "type": "portal"
      },
      "files": [],
      "js": "./plugin.ts",
      "css": "./plugin.scss",
      "template": {
        "index": "./public/index.html",
        "dev": "./public/dev.html",
        "entry": "./public/entry.html"
      }
    },
    "plugin": {
      "js": "./plugin.ts",
      "css": "./plugin.scss"
    }
  }
}

字段	说明	默认值
input	snack 模块目录	"src/package"
output	生产输出目录	"dist"
snack.externals	同 webpack externals，过滤不打包的依赖	{}
snack.buildIgnore	生产打包忽略的模块（模块目录名）	[]
snack.devPackage	开发模式仅启动指定模块，空数组表示全部启动	[]
snack.entry.name	入口页输出目录名	"entry"
snack.entry.id	所加载的页面 id	—
snack.entry.type	所加载的页面分类	—
snack.entry.title	HTML 页面 title	—
snack.entry.favicon	浏览器角标路径，相对项目根路径	—
snack.entry.service	snackbar 服务端地址，默认使用当前地址栏	—
snack.entry.devServer	调试服务网关	—
snack.entry.mobile	移动端页面配置，竖屏或宽度 < 1024px 时加载	—
snack.entry.files	需复制到发布目录的文件或目录路径	[]
snack.entry.js	外挂打包的 JS/TS 文件路径	—
snack.entry.css	外挂打包的 CSS/SCSS 文件路径	—
snack.entry.template	自定义 HTML 模板路径，相对项目根路径	—

config-overrides.js

在项目根目录创建 config-overrides.js 可自定义 webpack 配置。

注意： snack-scripts 会将已解析的 webpack 实例作为第二参数传入。若需使用 webpack 内置插件（如 ProvidePlugin），必须使用该参数而非 require('webpack')，否则会因 tapable 多实例冲突导致构建报错。

module.exports = (config, webpack) => {
    // 使用传入的 webpack 实例，而非 require('webpack')
    config.plugins = [
        ...config.plugins,
        new webpack.ProvidePlugin({ /* ... */ }),
    ];
    return config;
};

自定义模板

通过 --templatePath 参数指定自定义模板目录（需包含完整模板文件）：

{
  "scripts": {
    "start": "snack-cli start --templatePath=template",
    "build": "snack-cli build --templatePath=template",
    "entry": "snack-cli entry --templatePath=template"
  }
}

Changelog

0.9.1

• 修复：snack-scripts 命令在宿主项目中执行报 ENOENT 的问题，改用 require.resolve 动态定位 webpack-cli，兼容 npm hoist 和非 hoist 两种安装场景

0.9.0

• 修复：sass-loader 改回 legacy API，解决旧项目 @import '~xxx' 路径无法解析的问题（api: 'modern' 的 webpack importer 在 sass-loader 13.x 中未实现）
• 优化：添加 silenceDeprecations 配置，屏蔽 Dart Sass 1.80+ 对 @import、legacy JS API 等语法的弃用警告，迁移期间无需修改 SCSS 源文件

0.8.0

• 重构：bin/main.js 拆分为 snack-cli（init / create）和 snack-scripts（start / build / entry）两个独立命令
• 新增：snack-cli -v 查看当前版本号
• 新增：共享工具模块 bin/lib.js（语言检测、i18n 字符串、交互式提问工具）
• 修复：init 生成项目的 devDependencies 新增 @snack-kit/scripts，本地安装后不再依赖全局版本
• 修复：init 生成的 scripts 命令修正为 snack-scripts，与实际 bin 名一致

0.7.0

• 修复: 修复 loader.js 打包丢失的问题

0.6.0

• 新增：snack-cli 命令别名，与 snack-scripts 完全等价，snack-scripts 保留作为历史兼容
• 新增：init 命令支持交互式选择 React 版本（17 / 18 / 19），生成对应依赖版本
• 新增：CLI 提示语言跟随系统语言自动切换（LANG 环境变量，中文 / English）
• 修复：init 生成的 @snack-kit/core 版本从 ^0.1.0 修正为 ^0.3.0
• 修复：init 生成的 scripts 命令从 snack-scripts 更新为 snack-cli
• 优化：升级 sass-loader 至 v13，启用 Modern API（api: 'modern'），消除 Dart Sass Legacy JS API deprecation 警告

0.5.0

• 修复：默认渲染高度的问题

0.4.0

• 修复：调试窗口 topbar 工具区样式细节优化
• 修复：启动调试运行错误的问题
• 修复：修复 core 依赖版本错误的问题

0.3.0

• 新增：调试窗口 topbar 视口尺寸切换（PC / Tablet / Mobile / 自定义），偏好持久化到 localStorage
• 新增：调试窗口 topbar 内容区背景切换（默认 / 白色 / 深色 / 棋盘格透明检测）
• 新增：调试窗口 topbar 内容区缩放控制（50% / 75% / 100% / 125% / 150%）
• 新增：调试窗口 topbar 刷新模块按钮，强制重新 mount 当前模块

0.2.0

• 新增：MIGRATION.md 迁移指南，说明从 @para-snack/* / @paraview/* 迁移到 @snack-kit/* 的完整步骤
• 新增：config/webpack.shared.js 共享 webpack 配置模块
• 重构：template/dev/index.tsx、template/entry/index.tsx、template/snack/index.tsx 模板文件更新，适配新包名

0.1.0

• 新增：snack-scripts init [dir] 命令，交互式初始化新 snack 工程
• 新增：snack-scripts create 命令，交互式在工程内创建模块模版
• 重构：开发调试页（Snack Developer）全新 UI，支持浅色/深色主题切换，偏好持久化到 localStorage
• 重构：提取共享 webpack 配置（webpack.shared.js），消除各配置文件重复代码
• 优化：生产构建 loader.js 与 entry HTML 改为并行执行，提升构建速度
• 替换：@paraview/lib → @snack-kit/lib，支持全量 {} 导出，移除子路径引用
• 替换：@para-snack/core → @snack-kit/core
• 修复：utils/fs.js 中 CcopyFile 拼写错误及内部未定义函数引用
• 修复：webpack.snack.config.js 中冗余且路径错误的 babel-loader 规则
• 移除：vue-loader / VueLoaderPlugin 残留依赖
• 补充：minimist 加入 dependencies（原先漏声明）
• 规范：统一使用 const/箭头函数/可选链，for 循环改为 reduce/forEach

3.0.0-beta.1

• 支持 React 19

2.3.6

• exclude 增加 cjs，解决 axios 升级编译报错问题