前端构建工具中间件文档

1介绍

coolie-cli 中间件作用于构建工具构建的不同阶段,用来解决各种独立的应用场景。 官方内置的中间件就已经满足了大部分的日常需要。 当然,你也可以开发中间件来适配当前的业务场景。 在开发中间之前,需要了解以下内容。

2options

2.1options.progress

构建阶段,目前有值:

  • pre-html:构建 html 文件之前
  • post-html:构建 html 文件之后
  • post-config:配置文件解析之后
  • pre-static:静态文件路径解析之前
  • pre-module:模块解析之前
  • post-module:模块解析之后

其他参数根据 progress 的不同而不同。

3API

每一个中间件的执行上下文(this)都是当前构建的 coolie 对象:

coolie 对象上包装了以下接口:

3.1coolie.matchHTML(code, conditions, transform): undefined

匹配 html 并做相应转换。

3.1.1code

  • 类型:string
  • 说明:传入的代码

3.1.2conditions

  • 类型:object
  • 说明:传入的代码

匹配条件

  • conditions.tag<String|Array>,比如单个("a")或多个标签(["a", "b"]),使用*表示所有标签(此时仅能匹配非闭合标签
  • conditions.attrs<Object>,匹配属性,允许使用字符串和正则表达式
  • conditions.closed<Boolean>,默认自动匹配,指定是否为闭合标签(<a></a>为闭合标签)

3.1.3transform

  • 类型:function
  • 说明:转换方法会接收到一个参数 node,表示当前匹配到的节点,需要返回 node 信息(不能重写)

示例,匹配所有 a 标签,并加上 target="_blank"

coolie.matchHTML({
    tag: 'a'
}, function (node) {
    // <a></a>
    // <a href="#"></a>
    if (!node.attrs.href || node.attrs.href[0] === '#') {
        return node;
    }

    node.attrs.target = '_blank';
    return node;
});

3.2coolie.buildCSSPath(url, file, [options]): ret

构建单个 css 路径。

3.2.1url

  • 类型:string
  • 说明:需要构建的 URL,一般为本地的相对 url

3.2.2file

  • 类型:string
  • 说明:该 css 在哪个文件被使用

3.2.3options

  • 类型:object
  • 说明:配置

3.2.4options.srcDirname

  • 类型:string
  • 说明:源根目录

3.2.5options.destDirname

  • 类型:string
  • 说明:目标根目录

3.2.6options.destHost

  • 类型:string
  • 说明:目标域,可以包含协议、域名和路径

3.2.7options.destResourceDirname

  • 类型:string
  • 说明:目标资源目录

3.2.8options.destCSSDirname

  • 类型:string
  • 说明:目标样式目录

3.2.9options.minifyCSS

  • 类型:boolean
  • 说明:是否压缩 CSS

3.2.10options.minifyResource

  • 类型:string
  • 说明:是否压缩引用资源

3.2.11options.versionLength

  • 类型:number
  • 说明:版本号长度
  • 默认:32

3.2.12options.signCSS

  • 类型:boolean
  • 说明:是否 css 签名
  • 默认:false

3.2.13options.cleanCSSOptions

  • 类型:object
  • 说明:css 压缩配置
  • 默认:继承

3.2.14ret

  • 类型:object
  • 说明:构建结果对象

3.2.15ret.srcURL

  • 类型:string
  • 说明:源 URL

3.2.16ret.destURL

  • 类型:string
  • 说明:目标 URL

3.2.17ret.url

  • 类型:string
  • 说明:目标 URL

3.2.18ret.srcFile

  • 类型:string
  • 说明:源文件

3.2.19ret.destFile

  • 类型:string
  • 说明:目标文件

3.2.20ret.resList

  • 类型:array<string>
  • 说明:引用资源列表

示例,构建./css/style.css

var ret = coolie.buildCSSPath('./css/style.css', '/path/to/html/page.html');

if (!ret) {
    // 构建失败
}

// ret
// ret.url 构建之后的 url

3.3coolie.buildJSPath(url, file, [options]): ret

构建单个 js 路径。

3.3.1url

  • 类型:string
  • 说明:需要构建的 URL,一般为本地的相对 url

3.3.2file

  • 类型:string
  • 说明:该 js 在哪个文件被使用

3.3.3options

  • 类型:object
  • 说明:构建配置

3.3.4options.srcDirname

  • 类型:string
  • 说明:源根目录

3.3.5options.destDirname

  • 类型:string
  • 说明:目标根目录

3.3.6options.destHost

  • 类型:string
  • 说明:目标域,可以包含协议、域名和路径

3.3.7options.destJSDirname

  • 类型:string
  • 说明:目标脚本目录

3.3.8options.minifyJS

  • 类型:boolean
  • 说明:是否压缩 JS

3.3.9options.versionLength

  • 类型:number
  • 说明:版本号长度
  • 默认:32

3.3.10options.signJS

  • 类型:boolean
  • 说明:是否 JS 签名
  • 默认:false

3.3.11options.uglifyJSOptions

  • 类型:object
  • 说明:压缩配置
  • 默认:继承

3.3.12ret

  • 类型:object
  • 说明:构建结果对象

3.3.13ret.srcFile

  • 类型:string
  • 说明:源文件

3.3.14ret.destFile

  • 类型:string
  • 说明:目标文件

3.3.15ret.srcURL

  • 类型:string
  • 说明:源地址

3.3.16ret.destURL

  • 类型:string
  • 说明:目标地址

3.3.17ret.url

  • 类型:string
  • 说明:目标地址

示例,构建./js/app.js

var ret = coolie.buildCSSPath('./js/app.js', '/path/to/html/page.html');

if (!ret) {
    // 构建失败
}

// ret
// ret.url 构建之后的 url

3.4coolie.buildResPath(url, file, [options]): ret

构建单个资源路径。

3.4.1url

  • 类型:string
  • 说明:需要构建的 URL,一般为本地的相对 url

3.4.2file

  • 类型:string
  • 说明:该资源在哪个文件被使用

3.4.3option

  • 类型:object
  • 说明:配置

3.4.4options.srcDirname

  • 类型:string
  • 说明:源根目录

3.4.5options.destDirname

  • 类型:string
  • 说明:目标根目录

3.4.6options.destHost

  • 类型:string
  • 说明:目标域,可以包含协议、域名和路径

3.4.7options.destResourceDirname

  • 类型:string
  • 说明:目标资源目录

3.4.8options.versionLength

  • 类型:number
  • 说明:版本号长度
  • 默认:32

3.4.9ret

  • 类型:object
  • 说明:构建结果对象

3.4.10ret.srcFile

  • 类型:string
  • 说明:源文件

3.4.11ret.destFile

  • 类型:string
  • 说明:目标文件

3.4.12ret.srcURL

  • 类型:string
  • 说明:源地址

3.4.13ret.destURL

  • 类型:string
  • 说明:目标地址

3.4.14ret.url

  • 类型:string
  • 说明:目标地址

示例,构建./img/logo.png

var ret = coolie.buildCSSPath('./img/logo.js', '/path/to/html/page.html');

if (!ret) {
    // 构建失败
}

// ret
// ret.url 构建之后的 url

3.5coolie.parseRequire(file, name, [pipeline]): ret

分析依赖的模块信息。

3.5.1file

  • 类型:string
  • 说明:当前模块文件路径

3.5.2name

  • 类型:string
  • 说明:依赖的模块名称

3.5.3pipeline

  • 类型:string
  • 说明:管道描述
  • 默认:undefined

3.5.4ret

  • 类型:object
  • 说明:解析结果对象

3.5.5ret.name

  • 类型:string
  • 说明:同入参

3.5.6ret.pipeline

  • 类型:string
  • 说明:同入参

3.5.7ret.inType

  • 类型:string
  • 说明:入口类型

3.5.8ret.outType

  • 类型:string
  • 说明:出口类型
coolie.parseRequire('/path/to/main.js', 'abc.html');
// =>
{
    name: 'abc.html',
    pipeline: undefined,
    inType: 'html',
    outType: 'text'
}

3.6coolie.resolveModule(name, pipeline, options): ret

处理依赖的模块信息。

3.6.1name

  • 类型:string
  • 说明:依赖的模块名称

3.6.2pipeline

  • 类型:string
  • 说明:依赖的模块管道描述

3.6.3options

  • 类型:object
  • 说明:配置

3.6.4options.file

  • 类型:string
  • 说明:模块所在的文件路径

3.6.5options.srcDirname

  • 类型:string
  • 说明:源根目录

3.6.6ret

  • 类型:object
  • 说明:处理结果对象

3.6.7ret.name

  • 类型:string
  • 说明:同入参

3.6.8ret.pipeline

  • 类型:string
  • 说明:同入参

3.6.9ret.inType

  • 类型:string
  • 说明:入口类型

3.6.10ret.outType

  • 类型:string
  • 说明:出口类型

3.6.11ret.id

  • 类型:string
  • 说明:模块id

3.6.12ret.fullName

  • 类型:string
  • 说明:模块全名,当模块是简写的时候,如require('./abc'),name 是 ./abc,而 fullName 是 ./abc.js

3.6.13ret.nodeModule

  • 类型:boolean
  • 说明:是否为 node_modules 下的模块

3.7coolie.virtualFile(file, encoding, buffer): undefined

创建一个虚拟文件(虚拟文件不会占用磁盘空间,存在于内存中)。在特定情况下,需要创建一个虚拟文件来使用。 比如依赖了一个

require('abc.html')

在构建的时候,我们希望将 abc.html 转换为 function,避免生产解析 html 的步骤, 因此可以虚拟生成一个 js 文件,里面的内容是 function 代码。

3.7.1file

  • 类型:string
  • 说明:虚拟文件

3.7.2encoding

  • 类型:string
  • 说明:编码形式,可选 utf8binary

3.7.3buffer

  • 类型:Buffer
  • 说明:缓存内容