heirloom-static-plugin
基于Plugin
接口,对
koa-static、
koa-compress
以及
koa-webpack-dev-middleware、
koa-webpack-hot-middleware的封装实现。
文档
使用
新建工程:
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 = ;const heirloomStatic = ; const server = logger: console port: 4000 engine: heirloomServerKoaEngine; if processenvNODE_ENV === 'development' // Watch + 热更新 server; else // 启动时构建 + Gzip server; // open http://localhost:4000/app/sampleserverstart;
编写浏览器端静态资源example/public/sample/index.js
:
document;
编写浏览器端静态资源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.jsmoduleexports = 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的内容可为:
const API_ROOT = 'https://development.xuyuanxiang.me';
其它前端文件使用:
;
注意:使用eslint进行语法检查时,会对上面的引用报错找不到相应的包,可用// eslint-disable-next-line
注释。
环境变量
webpack.EnvironmentPlugin
默认从process.env
中采集:NODE_ENV
环境变量。
额外的环境变量或全局变量可通过新增的构造参数:define
传入:
服务器端初始化StaticPlugin
(或StaticDevPlugin
)时,传入define
参数:
...define: API_ROOT : "http://domain.com" FOO : processenvFOO
在浏览器端文件中,可获取全局变量:API_ROOT
及FOO
const response = ; // 读取 NODE_ENV:console;
webpack
配置参数
自定义使用方法:
在工程根目录下存放webpack.config.js
文件,StaticPlugin
会将该文件配置信息以最高优先级使用覆盖到默认配置中。
注意:目前自定义的webpack.config.js
文件中,只支持require
Node核心模块及node_modules下的自定义模块。不支持路径形式的模块。
关于样式
但推荐使用sass
.
已知问题:使用CSS Modules时,less-loader无法将.less
中url()
方法指向的图片正确加入到webpack构建流程。
postcss-import
heirloom-static-plugin
支持向如下方式引入你的项目中安装的依赖:
; /* 等价于 @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
方法错误的经历。
可以在你的入口文件中引入:
;
babel-preset-env
会根据targets.browsers
中所指定的目标浏览器版本自动将全量引入"babel-polyfill"转换为按需引入(Can I use)。
懒加载
heirloom-static-plugin
引入了babel-plugin-syntax-dynamic-import
依赖,支持webpack2动态加载:
应用场景示例(react-router懒加载):
path: '/about' { import"components/AboutPage";}
路由到/about
时,才会去加载有关的.js
文件。