node package manager

grunt-kmc

Grunt plugin for KISSY Module Compiler

grunt-kmc

KISSY Module Compiler的Grunt插件版本。

KISSY Module Compiler(kmc)是一个基于NodeJS的KISSY模块打包工具,目前适用于KISSY 1.2+的代码打包

如果您有任何问题,请提issue,或者邮件,或者来往(daxingplay)上联系我,阿里巴巴厂内用户还可以联系紫英。

依赖Grunt ~0.4.1,请首先安装Grunt,参照Grunt安装手册Gruntfile样例。之后,敲入命令来安装grunt-kmc:

npm install grunt-kmc --save-dev

然后,确保你的gruntfile.js中载入了这个模块

grunt.loadNpmTasks('grunt-kmc');

构建规则说明:基于 KISSY 的项目代码只要符合 KMD 规范,在源码发布上线之前,要做至少两件事

  1. 线上模块代码必须带有模块名配置
  2. 静态合并或者生成依赖关系的Map

在Gruntfile.js文件中,添加名为kmc的任务,代码块写在grunt.initConfig()函数参数对象中

grunt.initConfig({
kmc: {
options: {
depFilePath: 'build/mods.js',
comboOnly: true,
fixModuleName:true,
comboMap: true,
packages: [
{
name: 'package-name',
path: './src/',
charset:'utf-8',
ignorePackageNameInUri:true
 
}
],
},
main: {
files: [
{
expand: true,
cwd: 'src/',
src: [ '**/*' ],
dest: 'build/'
}
]
}
},
})
  • 类型: Array
  • 默认值: []

KISSY 包配置项,可以使用KISSY 1.2的数组方式,也可以使用KISSY 1.3+的对象方式。配置项的含义和KISSY的包配置规则完全一致,具体可参考KISSY loader的文档。比如:

packages: [
	{
		name: 'package-name',
		path: './src/',
		charset:'utf-8',
		ignorePackageNameInUri:true
	}
]

或者(推荐)

packages: {
	'package-name': {
		base: './src/',
		charset:'utf-8',
		ignorePackageNameInUri:true
	}
}
  • 类型: String
  • 默认值: utf-8

输入文件的编码

  • 类型: Boolean
  • 默认值: false

设置为true时,将不进行文件静态合并,比如两个文件a.jsb.js

a.js

// a.js
KISSY.add(function(S){
	// a
},{
	requires:['./b']
});

b.js

// b.js
KISSY.add(function(S){
	// b
});

comboOnlyfalse时将静态合并,比如a.js将生成为:

a.js

// b.js
KISSY.add('pkg/b',function(S){
	// b
});
// a.js
KISSY.add('pkg/a',function(S){
	// a
},{
	requires:['./b']
});

即所有的依赖也都合并到一个文件中。

  • 类型: Boolean
  • 默认值: false

comboOnlyfalse(静态合并)时,是否将没有指定合并的文件都删除,以减少构建后无用文件数量,cleanUptrue 时清除,为false时不清除

comboOnlytrue时此配置项不起作用

  • 类型: String
  • 默认值: ``

生成依赖关系表的文件(输出)位置

  • 类型: String
  • 默认值: 和options.charset保持一样

依赖关系表文件的编码类型

  • 类型:Boolean
  • 默认值:false

当指定模个文件为入口文件时,遍历子目录进行构建

  • 类型:Boolean
  • 默认值:false

置为true时,会给所有文件补全模块名,建议当comboOnlytrue时,总是设置此项为true 重要:fixModuleName会在指定的src上进行补全模块名,所以如果您需要使用combo模式并且需要补全模块名,请先用grunt-contrib-copy将您的src文件拷贝到dest,然后再对dest执行kmc任务。

  • 类型:Boolean
  • 默认值:false

当指定一批文件为源文件时,对这些文件只生成模块依赖关系表,存放于options.depFilePath

  • 类型:Boolean
  • 默认值:false

需要和fixModuleName搭配使用。 选项为true的时候,kmc会把src的文件拷贝到dest后再添加模块名。为false的时候,会直接在用户配置的src中的文件添加模块名。我们建议您如果有fixModuleName的需求的时候,先使用grunt-contrib-copy任务把src拷贝到dest,再执行grunt-kmc任务


如果静态合并:其中mods中的文件被index.jslist.js所依赖,Example

Before After
./src
├── mods
│   ├── a.js
│   ├── b.js
│   ├── c.js
│   └── d.js
└── pages
    └── home
        ├── index.js
        └── list.js
sample/build
└── pages
    └── home
        ├── index.js
        └── list.js

生成Map:Example

Before After
./src
├── mods
│   ├── a.js
│   ├── b.js
│   ├── c.js
│   └── d.js
└── pages
    └── home
        ├── index.js
        └── list.js
./build
├── mods
│   ├── a.js
│   ├── b.js
│   ├── c.js
│   └── d.js
├── map.js
└── pages
    └── home
        ├── index.js
        └── list.js

仅补全模块名:Example


入口为单个文件,将这个文件的依赖关系解析好后合并入另一个文件

grunt.initConfig({
	kmc: {
		main:{
			options: {
				packages: [
					{
						name: 'test',
						path: 'assets/src',
						charset: 'utf-8',
						ignorePackageNameInUri:true
					}
				]
			},
			files: [{
				// 入口和出口均为单文件
				src: 'assets/src/test/index.js',
				dest: 'assets/dist/test/index.combo.js'
			}]
		}
	}
});

详细配置项请参照kmc首页

如果输出gbk编码的文件,需要配置全局项

kmc: {
	options: {
		charset:'gbk',
		packages: [
			{
				name: 'pkg-name',
				path: '../',
				charset:'gbk',
				ignorePackageNameInUri:true
			}
		]
	},
//...
grunt.file.defaultEncoding = 'gbk';

入口为一批文件,每个文件都解析合并

grunt.initConfig({
    kmc: {
        options: {
            packages: [
                {
                    name: 'pkg-name',
                    path: '../',
					charset:'utf-8',
					ignorePackageNameInUri:true

                }
            ],
			// 将 ModuleName 中的 `src` 去掉
			map: [['pkg-name/src/', 'pkg-name/']]
        },

        main: {
            files: [
                {
					// 这里指定项目根目录下所有文件为入口文件
                    expand: true,
					cwd: 'src/',
                    src: [ '**/*.js', '!Gruntfile.js'],
                    dest: 'build/'
                }
            ]
        }
	}
});

入口为一批文件,每个文件都解析合并,包名从配置文件中读取

grunt.initConfig({
	// 读取`abc.json配置文件中的配置`
    pkg: grunt.file.readJSON('abc.json'),
    kmc: {
        options: {
            packages: [
                {
                    name: '<%= pkg.name %>',
                    path: '../',
					charset:'utf-8',
					ignorePackageNameInUri:true
                }
            ],
			// 将 ModuleName 中的 `src` 去掉
			map: [['<%= pkg.name %>/src/', '<%= pkg.name %>/']]
        },

        main: {
            files: [
                {
					// 这里指定项目根目录下所有文件为入口文件
                    expand: true,
					cwd: 'src/',
                    src: [ '**/*.js', '!Gruntfile.js'],
                    dest: 'build/'
                }
            ]
        }
	}
});

其中 abc.json 文件内容如下:

{
	"name": "my-custom-package-name",
}

生成模块依赖关系表,同时源文件也被添加好模块名存放到目标目录

grunt.initConfig({
	options: {
		packages: [
			{
				name: 'h5-test',
				path: './src/', //指定package起始路径
				charset:'utf-8',
				ignorePackageNameInUri:true
			}
		],
		// 生成模块依赖关系表
		depFilePath:'build/mods.js',
		comboOnly:true,// 不要静态合并
		fixModuleName:true,// 补全模块名称
		comboMap:true
	},
	main: {
		files: [
			{
				src: 'src/**/*.js',
				dest: 'build/'
			}
		]
	}
});

Clam工具和阿里内部工具ABC依赖kmc。


比如

/*generated by KMC*/
KISSY.config('modules', {
 'xcake/app/cjs-full': { requires: ['node', '/home/bachi/xx/node-kpc/sample/src/components/header/index.js']},
 'xcake/app/cjs': { requires: ['node', '/home/bachi/xx/node-kpc/sample/src/components/header/index.js']},
 'xcake/app/fac-config': { requires: ['node']},
 'xcake/app/namedMod2': { requires: ['node', '/home/bachi/xx/node-kpc/sample/src/app/mod.js']} 
});

原因是header/index.js文件不存在。


  • 0.1.15 bugfix for comboOnly & comboMap
  • 0.1.7 bugfix for comboMap
  • 0.1.6 add traverse option.
  • 0.1.5 fix charset output bug.