nwb Preact 应用开发工作流指南:从依赖安装、热更新开发到测试与构建
nwb Preact 应用开发工作流指南:从依赖安装、热更新开发到测试与构建
本文以 nwb 仓库中 preact-app 项目模板的 CONTRIBUTING.md 为主线,结合仓库源码(命令实现、测试与构建链路、Karma 配置)展开,系统讲解一个由 nwb 生成的 Preact 应用在日常开发中的完整工作流:环境准备、依赖安装、开发服务器(热模块替换)、单元测试(含覆盖率与监听模式)、生产/开发构建以及清理产物。读完本文,你将掌握每个 npm 脚本背后的 nwb 命令、底层执行链路与可调参数,能够在新生成的 Preact 应用中直接上手开发、测试与发布构建。
前置条件:Node.js 环境
模板 CONTRIBUTING.md 明确要求:
- 必须安装 Node.js >= 10。
nwb 本身通过 nwb 命令行驱动 Webpack、Karma、Babel 等工具链,这些工具都运行在 Node.js 之上,因此较新且稳定的 LTS 版本 Node.js 是唯一硬性前提。此外,nwb 项目创建时会自动执行 git init 并提交初始 commit(除非传入 --no-git,见 createProject.js),所以本机装有 Git 也会让后续版本管理更顺畅。
安装依赖:npm install
在应用根目录执行:
npm install
该命令会读取生成项目中的 package.json 安装全部开发依赖。生成模板的包清单位于 templates/preact-app/_package.json,其中把 nwb 本身作为 devDependency 写入(版本号为创建项目时 nwb 的当前版本),并把全部开发命令预置为 npm scripts:
{
"scripts": {
"build": "nwb build-preact-app",
"clean": "nwb clean-app",
"start": "nwb serve-preact-app",
"test": "nwb test-preact",
"test:coverage": "nwb test-preact --coverage",
"test:watch": "nwb test-preact --server"
},
"devDependencies": {
"nwb": "{{nwbVersion}}"
}
}
模板中的 {{name}}、{{nwbVersion}} 会在 nwb new preact-app <name> 或 nwb init preact-app 创建项目时由 createProject.js 通过模板渲染替换为真实项目名与 nwb 版本。
注:nwb 在运行
build、serve、test等命令时会校验“正在运行的 nwb 版本”与项目package.json中声明的 nwb 版本是否匹配(semver 满足),不满足会直接报错并终止,见 cli.js。这也是把 nwb 作为本地 devDependency 安装的意义所在。
开发服务器:npm start
执行:
npm start
nwb 会启动 Webpack 开发服务器,应用运行在 http://localhost:3000,并默认开启 Hot Module Replacement(热模块替换,HMR)——修改代码保存后页面自动更新,无需手动刷新。
背后的命令与源码链路
npm start 实际执行 nwb serve-preact-app(入口 serve-preact-app.js),它调用通用 serve()(appCommands.js)生成开发配置并交给 Webpack 开发服务器。默认端口来自 constants.js 的 DEFAULT_PORT = process.env.PORT || 3000,因此你也可以通过环境变量改变端口:
PORT=8080 npm start
模板应用入口 templates/preact-app/src/index.js 展示了 HMR 的标准写法:在 module.hot 存在时 module.hot.accept('./App', init),从而在 App 模块变更后自动重新渲染。应用被渲染进 #app 这个 DOM 节点。
Preact 专属配置:兼容层与渲染 Shimming
Preact 项目配置定义在 src/preact/index.js,其中将 react 与 react-dom 都 alias 到 preact/compat,并把 react-dom/test-utils alias 到 preact/test-utils,这意味着在 Preact 应用中可以直接 import 兼容 React 的第三方组件。JSX 编译则由 src/preact/preact-preset.js 指定 pragma: 'h'、pragmaFrag: 'Fragment'。
此外,nwb 为 Preact 提供了渲染 Shim(src/preact/renderShim.js):开发环境下自动 require('preact/debug') 启用 Preact Devtools,并把入口模块导出内容挂载到 NWB_QUICK_MOUNT_ID(默认 app)对应的 DOM 节点上,同时处理顶层 HMR 的重新渲染。
运行测试
生成项目提供三个测试相关脚本:
npm test # 运行一次测试
npm run test:coverage # 运行测试并生成覆盖率报告到 coverage/
npm run test:watch # 监听文件变化,每次变更自动重跑测试
三者分别对应:
nwb test-preactnwb test-preact --coveragenwb test-preact --server
测试执行链路与默认配置
nwb test-preact(test-preact.js)调用 karmaServer.js,它会强制 NODE_ENV=test,再基于项目类型配置生成 Karma 配置并启动 Karma Server。默认行为(见 createKarmaConfig.js)包括:
- 浏览器:
ChromeHeadless(无头 Chrome); - 测试框架:
mocha+webpack(测试文件同样经 Webpack 编译打包); - 测试文件匹配:默认匹配
+(src|test?(s))/**/*+(.spec|.test).js,即src/或tests/下所有.spec.js/.test.js(也支持与源码同目录的__tests__目录,覆盖率计算默认排除test/、tests/、src/**/__tests__/)。
模板自带的示例测试 templates/preact-app/tests/App.test.js 使用 expect 断言库与 preact 的 render() 把 <App/> 渲染进临时 DOM 节点,再断言文本内容,可直接作为编写组件测试的范式。
覆盖率报告
--coverage 会在 createKarmaConfig.js 中启用 babel-plugin-istanbul 插桩,并将报告输出到项目根目录的 coverage/,同时生成:
coverage/html(HTML 报告)coverage/lcovonly(lcov 格式)text-summary(终端摘要)
另外,在 CI 环境(设置了 CI 或 CONTINUOUS_INTEGRATION 环境变量)下运行测试会自动强制开启覆盖率并单次运行(singleRun: true);普通本地运行则取决于是否传入 --server——--server 会让 Karma 持续监听并重跑,这正是 test:watch 的原理。
构建:npm run build
npm run build
默认创建 生产构建,产物输出到应用根目录的 dist/。若需要 开发构建,在运行命令时设置 NODE_ENV 环境变量为 development:
NODE_ENV=development npm run build
构建链路与产物细节
npm run build 实际执行 nwb build-preact-app(build-preact-app.js),通用构建逻辑见 appCommands.js:它会先执行 clean-app 清理旧产物,再调用 Webpack 编译。若 NODE_ENV 未设置,webpackBuild.js 会将其默认置为 production,这也解释了为什么 npm run build 默认就是生产构建。
产物命名规则在 appCommands.js 中定义:
- 生产构建:
[name].[chunkhash:8].js(带 8 位内容哈希,利于长期缓存); - 开发构建:
[name].js(无哈希)。
构建配置还包含以下默认行为:
- Babel 目标:生产环境默认 targets 为
>0.2%, not dead, not op_mini all(见 constants.js),即面向主流现代浏览器做 ES5 转译与 polyfill; - HTML 模板:使用项目
src/index.html(若存在),否则回退到内置模板(lang、mountId: 'app'、title取package.json的 name,见 appCommands.js); - public 目录拷贝:若项目根目录存在
public/,其中的静态资源会被原样复制到构建产物(模板 templates/preact-app/public/ 仅含.gitkeep占位); - vendor 拆分:默认会把来自
node_modules/的模块拆分为独立的vendorbundle(可用--no-vendor关闭)。
清理构建产物:npm run clean
npm run clean
对应命令为 nwb clean-app(clean-app.js),默认删除 coverage/ 与 dist/ 两个目录(也支持 nwb clean-app <a href="https://link.gitcode.com/i/7a24e75f664d10ba3cf5af1f670e904b" target="_blank">dist_dir] 指定要清理的输出目录)。生成项目的 [_.gitignore 也恰好忽略了 /coverage、/dist 与 /node_modules,保证这些生成物不会进入版本库。
项目类型标识:nwb.config.js
生成项目根目录自带一个 nwb.config.js:
module.exports = {
type: 'preact-app'
}
type: 'preact-app' 用于让通用命令(nwb serve、nwb build、nwb test)自动识别项目类型并分派到对应的 Preact 命令——分派逻辑见 serve.js 与 build.js 中的 SERVE_COMMANDS / BUILD_COMMANDS 映射表。换言之,即便不写死 nwb serve-preact-app,在项目内直接运行 nwb serve 也能得到完全相同的行为。
工作流速查
| 阶段 | 命令 | 底层 nwb 命令 | 说明 |
|---|---|---|---|
| 安装 | npm install |
— | 安装全部依赖(含本地 nwb) |
| 开发 | npm start |
nwb serve-preact-app |
开发服务器 @ http://localhost:3000,支持 HMR |
| 测试 | npm test |
nwb test-preact |
Karma + Mocha + Webpack,ChromeHeadless 运行一次 |
| 覆盖率 | npm run test:coverage |
nwb test-preact --coverage |
生成报告到 coverage/ |
| 监听测试 | npm run test:watch |
nwb test-preact --server |
文件变更自动重跑 |
| 构建 | npm run build |
nwb build-preact-app |
默认生产构建,产物在 dist/ |
| 开发构建 | NODE_ENV=development npm run build |
同上 | 无哈希文件名,便于调试 |
| 清理 | npm run clean |
nwb clean-app |
删除 coverage/ 与 dist/ |
这套工作流覆盖了从拿到新生成的 nwb Preact 应用到完成一次可发布构建的全部环节。理解每个脚本背后的 nwb 命令与配置默认值(端口、测试匹配规则、覆盖率输出、构建哈希、浏览器目标等),可以让你在需要时用 --port、--config、--plugins 等参数或修改 nwb.config.js 平滑地定制开发体验,而无需手写任何 Webpack / Karma 配置。