heirloom-static-plugin

• koa 2.x.x

基于Plugin接口，对 koa-static、 koa-compress 以及 koa-webpack-dev-middleware、 koa-webpack-hot-middleware的封装实现。

文档

1. 如何在Docker构建过程中构建静态资源

使用

新建工程：

mkdir example && cd example && npm init

配合heirloom-core项目使用

安装依赖：

SASS_BINARY_SITE=https://npm.taobao.org/mirrors/node-sass/ npm install heirloom-core heirloom-static-plugin --save

编写example/index.js:

const heirloomServer = require("heirloom-core");
const heirloomStatic = require("heirloom-static-plugin");

const server = new heirloomServer.NormalServer({
    logger: console,
    port: 4000,
    engine: heirloomServer.KoaEngine.shareInstance(),
});

if (process.env.NODE_ENV === 'development') {
    // Watch + 热更新
    server.apply(new heirloomStatic.StaticDevPlugin({
        root: __dirname,
        source: "public",
        config: "public/config",
        publicPath: "/app",
        define: { API_ROOT : "http://domain.com" },
    }));
} else {
    // 启动时构建 + Gzip
    server.apply(new heirloomStatic.StaticPlugin({
        root: __dirname, // 选填，缺省（默认）：process.cwd()
        source: "public", // 选填，静态资源探测目录，缺省（默认）：join(process.cwd(), 'public')
        target: "dist", // 选填，构建生成目标目录，缺省（默认）：join(process.cwd(), 'dist')
        publicPath: "/app", // 选填，指定静态资源路径到：http://localhost:4000/app，缺省（默认）：／
        config: "public/config", // 选填，指定前端环境变量目录
        oss: "aliyun", // 选填，"none" - 不上传OSS， "aliyun" - 上传至阿里云OSS，缺省（默认）：none
        aliyun: { // oss === 'aliyun'时，必填
            domain: 'https://domain.com',
            region: 'oss-cn-hangzhou',
            accessKeyId: '***',
            accessKeySecret: '***',
            bucket: 'your-bucket',
        },
        define: { API_ROOT : "http://domain.com", FOO: 'foo' }, // 选填，定义静态资源JS中全局变量API_ROOT和FOO的值
    }));
}

// open http://localhost:4000/app/sample
server.start();

编写浏览器端静态资源example/public/sample/index.js:

document.writeln("<h1>Hello World!</h1>");

编写浏览器端静态资源example/public/sample/package.json:

{
  "name": "sample",
  "title": "演示"
  "description": "这是一个示例",
  "keywords": [
    "heirloom",
    "static sample"
  ],
  "main": "index.js"
}

作为命令行工具单独使用

在example/根目录下执行：

heirloom

可以创建example/heirloom.config.js文件，导出StaticPlugin的构造参数，供heirloom采集使用：

// heirloom.config.js
module.exports = {
    root: __dirname, // 选填，缺省（默认）：process.cwd()
    source: "public", // 选填，静态资源探测目录，缺省（默认）：join(process.cwd(), 'public')
    target: "dist", // 选填，构建生成目标目录，缺省（默认）：join(process.cwd(), 'dist')
    publicPath: "/app", // 选填，指定静态资源路径到：http://localhost:4000/app，缺省（默认）：／
    config: "public/config", // 选填，指定前端环境变量目录
    oss: "aliyun", // 选填，"none" - 不上传OSS， "aliyun" - 上传至阿里云OSS，缺省（默认）：none
    aliyun: { // oss === 'aliyun'时，必填
        domain: 'https://domain.com',
        region: 'oss-cn-hangzhou',
        accessKeyId: '***',
        accessKeySecret: '***',
        bucket: 'your-bucket',
    },
    define: { API_ROOT : "http://domain.com", FOO: 'foo' }, // 选填，定义静态资源JS中全局变量API_ROOT和FOO的值
};

package.json配置约定

一个目录如果包含package.json文件将会被加入到构建流程中， 反之，将作为静态资源被拷贝至目标目录下。

示例：

{
  "name": "sample",
  "title": "演示"
  "description": "这是一个示例",
  "keywords": [
    "heirloom",
    "static sample"
  ],
  "main": "index.js",
  "homepage": "index.ejs",
  "mobile": true,
  "growing": {
    "accountId": ""
  },
  "bughd": {
    "key": ""
  }
}

• name：路由，缺省，为该目录文件夹名。
• homepage：首页（index.html）模板文件。缺省，采用默认的HTML模板。
• main：入口文件。缺省，为index.js。如果入口文件不存在则中断构建。

以下属性，在homepage未设置时有效：

• growing: growing.io 配置
• bughd: bughd 配置
• mobile: true-移动端高清、多屏适配方案

静态资源自动检测

通过构造参数source，标明静态资源所处的目录。

StaticPlugin会探测source目录及其所有子目录，递归采集所有包含package.json文件目录，从package.json中获取构建所需的信息。

package.json的name和main即webpack配置参数中：entry属性的key和value。

配置前端环境变量

通过构造参数config，标明前端环境变量的目录。

构建前端资源时，可通过指定node.js的环境变量NODE_ENV和config目录下的对应文件名来指定前端环境变量。如果配置config，没有创建相对应的confg文件，则会报错。NODE_ENV默认值为develpment。

示例：

构造参数config值为public/config, NODE_ENV的值为develpment和production。则以下目录和文件应存在：

public/
├── config/
│   ├── develpment.js-----------------------包含development环境下的变量
│   ├── production.js--------------------------包含development环境下的变量

develpment.js的内容可为：

export const API_ROOT = 'https://development.xuyuanxiang.me';

其它前端文件使用：

import { API_ROOT } from 'Config';

注意：使用eslint进行语法检查时，会对上面的引用报错找不到相应的包，可用// eslint-disable-next-line注释。

环境变量

webpack.EnvironmentPlugin默认从process.env中采集：NODE_ENV环境变量。

额外的环境变量或全局变量可通过新增的构造参数：define传入：

服务器端初始化StaticPlugin（或StaticDevPlugin）时，传入define参数：

new StaticPlugin({
...,
define: { API_ROOT : "http://domain.com",  FOO : process.env.FOO },
})

在浏览器端文件中，可获取全局变量：API_ROOT及FOO

const response = fetch(`${API_ROOT}/api/v1/foo?foo=%{FOO}`)；

// 读取 NODE_ENV：
console.log(process.env.NODE_ENV);

自定义webpack配置参数

使用方法：

在工程根目录下存放webpack.config.js文件，StaticPlugin会将该文件配置信息以最高优先级使用覆盖到默认配置中。

注意：目前自定义的webpack.config.js文件中，只支持requireNode核心模块及node_modules下的自定义模块。不支持路径形式的模块。

关于样式

但推荐使用sass.

已知问题：使用CSS Modules时，less-loader无法将.less中url()方法指向的图片正确加入到webpack构建流程。

postcss-import

heirloom-static-plugin支持向如下方式引入你的项目中安装的依赖：

@import "normalize.css"; /* 等价于 @import "./node_modules/normalize.css/normalize.css"; */

Babel

默认.babelrc文件

这是目前heirloom-static-plugin构建所采用的.babelrc配置:

const browsers = [
    'Android 2.3',
    'Android >= 4',
    'Chrome >= 35',
    'Firefox >= 31',
    'Explorer >= 9',
    'iOS >= 7',
    'Opera >= 12',
    'Safari >= 7.1',
];

const babelPlugins = [
    'syntax-dynamic-import',
];

if (process.env.NODE_ENV === 'production') {
    babelPlugins.push('transform-remove-console', 'transform-react-remove-prop-types');
}


ignore: 'node_modules',
presets: [
    [
        'env',
        {
            useBuiltIns: true,
            targets: { browsers },
        },
    ],
    'flow',
    'es2017',
    'react',
    'stage-1',
],
plugins: babelPlugins,

如果你的工程根目录下存在.babelrc会覆盖以上配置。

关于Polyfill

不建议使用babel-runtime + babel-plugin-transform-runtime。我曾有过在Android 4.x.x版本中报缺少Array.includes方法错误的经历。

可以在你的入口文件中引入：

import "babel-polyfill";

babel-preset-env会根据targets.browsers中所指定的目标浏览器版本自动将全量引入"babel-polyfill"转换为按需引入（Can I use)。

懒加载

heirloom-static-plugin引入了babel-plugin-syntax-dynamic-import依赖，支持webpack2动态加载：

应用场景示例（react-router懒加载）：

path: '/about',
getComponent: (nextState, cb) => {
    import("components/AboutPage").then(module => cb(null, module.default));
},

路由到/about时，才会去加载有关的.js文件。