工程配置

icejs 基于 build-scripts，因此工程使用方式与 build-scripts 完全一致。

开发调试

默认情况下，项目的 package.json 会配置以下命令：

  1. {
  2.   "scripts": {
  3.     "start": "icejs start",
  4.     "build": "icejs build"
  5.   }
  6. }

执行 npm start 即可进行项目开发，正常情况下执行命令后自动打开浏览器 http://localhost:3333 进行页面预览，修改源码后浏览器会自动刷新页面。执行 npm run build 进行项目构建，构建产物默认输出到 ./build 目录下。

命令行介绍

icejs 提供了 start/build 两个核心命令供开发者使用。

在使用 npm run start 命令时，如需传入参数请按照这个格式 npm run start -- --https

start

  1. $ icejs start --help
  3. Usage: icejs start [options]
  5. Options:
  6.   --port <port>          服务端口号
  7.   --host <host>          服务主机名
  8.   --config <config>      指定配置文件
  9.   --https                支持开启 https
  10.   --analyzer             支持开启构建分析
  11.   --analyzer-port <port> 支持定制构建分析端口
  12.   --disable-reload       禁用热更新模块
  13.   --disable-mock         禁用 mock 服务
  14.   --disable-open         禁止浏览器默认打开行为
  15.   --disable-assets       禁止 Webpack assets 的输出
  16.   --force                移除构建缓存

build

  1. $ icejs build --help
  3. Usage: icejs build [options]
  5. Options:
  6.   --analyzer             同 start
  7.   --analyzer-port <port> 同 start
  8.   --config <config>      同 start
  9.   --force                同 start

工程构建配置

工程构建相关的配置默认都收敛在项目根目录的 build.json 文件中，配置方式：

  1. {
  2.   "alias": {},
  3.   "publicPath": ""
  4. }

如果希望使用 JS 类型的配置文件，则需要在 npm scripts 中指定配置文件：

  1. {
  2.   "scripts": {
  3.     "start": "icejs start --config build.config.js",
  4.     "build": "icejs build --config build.config.js"
  5.   }
  6. }

build.config.js 中通过 JS 模块的方式指定配置：

  1. module.exports = {
  2.   define: {
  3.     env: process.env.NODE_ENV,
  4.   },
  5.   plugins: [
  6.     [
  7.       'build-plugin-fusion',
  8.       {
  9.         themePackage: '@icedesign/theme',
  10.       },
  11.     ],
  12.     (api) => {
  13.       api.onGetWebpackConfig((config) => {
  14.         config.entry('src/index.js');
  15.       });
  16.     },
  17.   ],
  18. };

当下支持的基础配置项请参考文档：配置。

进阶配置

根据环境区分工程配置

参考 区分不同环境。

如何开启新的 JSX 转换

ice.js 1.16.0+ 支持 New JSX Transform，开启该能力之后，编写 React 组件时不再需要在头部引入 React。

只需要修改 tsconfig.json 中的 compilerOptions.jsx 即可：

  1. {
  2.   "compilerOptions": {
  3. -    "jsx": "react",
  4. +    "jsx": "react-jsx",
  5.   }
  6. }

接下来书写组件就不再需要引入 React 了：

  1. - import React from 'react';
  3. function Example() {
  4.   return <>Hello</>;
  5. }

自定义工程配置

如果基础配置和已有插件都无法支持业务需求，可以通过自定义配置来实现，自定义配置同时也是一个 Webpack 插件。

首先新建 build.plugin.js 文件作为一个自定义插件，然后写入以下代码：

  1. module.exports = ({ context, onGetWebpackConfig }) => {
  2.   onGetWebpackConfig((config) => {});
  3. };

插件内部代码写法可以参考文档 通过插件定制工程能力。

最后在 build.json 里引入自定义插件即可：

  1. {
  2.   "plugins": ["build-plugin-ice-app", "./build.plugin.js"]
  3. }

调试

在某些情况下可能遇到配置没有生效，或者配置不符合预期，这时候我们可以通过下面的命令进行调试，查看最终的 Webpack 配置是否符合预期。

  1. # 调试开发环境
  2. $ DEBUG=icejs npm start
  4. # 调试构建环境
  5. $ DEBUG=icejs npm run build
  7. # 调试构建环境
  8. $ DEBUG=icejs npm run test