GruntJS plugin for KISSY Module Compiler
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
tasks
test
.gitignore
.jshintrc
.npmignore
.travis.yml
Gruntfile.js
LICENSE-MIT
README.md
package.json

README.md

grunt-kmc

Build Status

NPM version

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 任务

介绍

在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/'
				}
			]
		}
	},
})

配置项

options.packages

  • 类型: 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
	}
}

options.charset

  • 类型: String
  • 默认值: utf-8

输入文件的编码

options.comboOnly

  • 类型: 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']
});

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

options.cleanUp

  • 类型: Boolean
  • 默认值: false

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

comboOnlytrue时此配置项不起作用

options.depFilePath

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

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

options.depFileCharset

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

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

options.traverse

  • 类型:Boolean
  • 默认值:false

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

options.fixModuleName

  • 类型:Boolean
  • 默认值:false

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

options.comboMap

  • 类型:Boolean
  • 默认值:false

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

options.copyAssets

  • 类型:Boolean
  • 默认值:false

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


用法

Example1

如果静态合并:其中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

Example2

生成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

Example3

仅补全模块名:Example


更多配置写法参考

示例1,单文件静态合并

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

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';

示例2,批量静态合并文件

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

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/'
                }
            ]
        }
	}
});

示例3,批量静态合并,包名为变量

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

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",
}

示例4,针对一批文件生成依赖关系表

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

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。


Q & A

生成的Map文件依赖地址怎么有绝对地址?

比如

/*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文件不存在。


Changelog

  • 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.