Gulpman NPM | npm.io

gulpman

浏览简体中文文档

Create Modular Front-End Build System, organize the source by module, using relative path, html/js/css/img/fonts/tpl are in one same folder, like Baidu FIS. Good concept for FE source management / development.
Concept Introduction: 前端工程之模块化
Component Oriented Solution, based on gulp. More simple, flexible, expandable and stable. Everyone know gulp can do secondary development.
Support base64 image in html/CSS
Support JS/CSS inlnied in html
Support require('main.css'), require css file in js
Intergrated with spritesmith, support auto sprite img
Intergrated with icon-font, support SVG 2 Iconfont.
Intergrated with usemin，support complex combo/package.
Supoort FE Tpl embed function， the .tpl file will packaged into js file，support async js loading.
Intergrated with SCSS|ES6|ReactJS|Vuejs|Babel|Browserify|cssnano|uglify|imagmein and other plugins，One-Stop Solution Service， very Simple and Strong
High scalability, compatiable with almost gulp plugins, you can use them in gulpman. For example, you can put browser-sync in your gulpman build system
Intergrated with karma framework，support babel/es6 unit test and coverage result.

Introduction

Support Mac、Linux
No full test under Windows. You can install gulp、gulp-sass manually
Required Node >= 4.0.0

Install

npm install gulpman --save-dev
Run gulp gm:install to finish the setup
*If in China, please use cnpm to install it: cnpm install gulpman --save-dev

Note

If gulp-sass install failed, please run cnpm install gulp-sass gulp-imagemin by manual to fix that.
If error happened in npm install，such as /usr/local/lib/node_modules permission error, fix this by sudo chown -R "$(whoami)"+Path
sudo npm install is not recommended
The imagemin-pngquant module needlibpng-devel，if in Linux, please run yum install libpng-devel at first
If install failed, check the npm-debug.log to see if there are some ENOMEMerrors

Config

0. Support Auto Mode, no Config

You can skip Config, and directly jump to Usage

1. Config gulpfile.js:

require the gulpman in your gulpfile.js，then it will load gm:publish, gm:develop into gulp tasks.
gulp gm:publish or gulp gm:develop in terminal then it will work

/**
 * Gulpfile.js
 */


var gulp = require('gulp'),
    gman = require('gulpman')

// your other tasks ...
// xxx ...


/**
 * config gulpman ======================
 * Use config API
 * assets path, CDN, URL prefix
 */

gman.config({
    
    // whether use absolute path, default `true` 
    'is_absolute': true,

    // cdn prefix support［string|array|function］arguments
    'cdn_prefix': '', 

    // url prefix, defautl `/static`. This involves the server config ,such as the static path of nginx
    'url_prefix': '/static',


    /** use spritesmith for css-img sprite
     * Based on Spritesmith: https://github.com/Ensighten/spritesmith
     * Automatecially generate Sprite Image & CSS
     **/
    //'spritesmith': { },
    
    /** usemin config **/
    // 'usemin': {}


    // The COMPONENTS directory
    'components': 'components',

    // For development assets and templates folder, related to Server Config
    'runtime_views': 'views',
    'dist_views': 'views_dist',

    // For production assets and templates folder, related to Server Config
    'runtime_assets': 'assets',
    'dist_assets': 'assets_dist',

    // The js library dir, set as a global module. Also you can set as `bower_components`
    'lib': 'lib', 

    // You can add one customer global directory, so you can require module name directly, like: `require ('xxx')`. The xxx is in this directory
    'global': 'common' 
})

2. How to config CDN better

cdn_prefix support String, Array, Function
if argument is array, the CDN will be an random value
if argument is function，it would input one argument, mediaFile

'cdn_prefix': function (fileName) {
        
        console.log(fileName)

        var c_list = [
            'http://s0.com', 
            'http://s1.com', 
            'http://s2.com', 
            'http://s3.com',
            'http://s4.com'
        ]
        // You can customized your strategy
        if(hostFile.match(/\.html$/gm)){
            return c_list[0]
        }else {
            return c_list[1]
        }
    },

3. About `is_absolute`

is_absolute is the dist path of source in html. default true. the dist path is like /static/home/main.js
*Need consistent config with Server, like nginx, apache
If no local server, you can set is_absolute as false, use relative path. Like ../../assets/static/home/main.js

4. gulpman directory

Use gulpman to arrange your directory as component，The root component dir can be./components(default). If you have one component named foo, then ./components/foo，all related assets such as html|js|css|fonts|image should be put in foo folder.
This solution for assets can be high efficiency and easy to maintain.
gm:develop to start develop mode, the views dir and assets dir can be generated automatically
gm:publish to publish assets in production env. The views_dist and assets_dist can generated.

5. What is global directory

For Browserify packing, the js module in global dir can be directly require or import in es6/js code
In gulpman.config, the lib和global are global directory. Take an example:

In components/lib directory, you have one module foo.js，then it is components/lib/foo.js. So when you use foo in your es6 file, you can use it like: import foo from 'foo', no need write as import foo from '../lib/foo'

similarly, global option can set your dir as global module dir. You can set bower dir as your lib dir.
Please make no conficts in your global dir

6. Support for complex and multi level directory in config

Such as:

gulpman.config({
    'is_absolute': false,
    'components': 'components/cc',
    'runtime_views': 'runtime_views/rv',
    'dist_views': 'dist_views/dv/dv',

    'dist_assets': 'dist_assets/da',
    'runtime_assets': 'runtime_assets/ra/ra',
})

Usage

1. CLI run Task:

# Create components directory and add one demo
# init components dir and a html demo
gulp gm:init


# develop and watch mode，watchings files changes and update files
gulp gm:develop

# Build and Watch one special component, other files are not compiled
gulp gm:develop -c component_name1,component_name2,component_name3...


# publish assets in production env
gulp gm:publish

# publish command support `-a`和`-v` parameters to set output assets/views path.
gulp gm:publish -v your_views_dist -a your_assets_dist

# clean dist files
gulp gm:clean

# clean dist files, including subfolders
gulp gm:clean-deep

# Generate one developing assets/views files, but not in watching mode
# compile for develop, not watch
gulp gm:compile

2. Watch one special component in development

When the project become huge, if we watch all components assets, it will be slow and low efficiency, so we can only watch special component to get better performance
Fox example, if we want watch the home component:

# this will only build and watch `components/home` components
gulp gm:develop -c home

3. Use `React` in gulpman

Install React: npm install react react-dom
Use React in ES6:

import React from 'react';
import ReactDOM from 'react-dom';

// xxx

4. Use `tpl` file in js|es6|jsx

Support .tpl file, it will be packaged in dist js files.
Usage: import dialogTpl from './dialog.tpl' or var dialogTpl = require('./dialog.tpl')

5. Usge base64 img in HTML/CSS

Just add ?_gm_inline in assets src path in html/css
The base64 code will be inlined in html/css

html

<p class="play"> 
    <img width="480" alt="Karat 克拉" src="./img/testb64.png?_gm_inline" />
</p>

CSS/SCSS

.test {
    background: url(./img/testb64.png?_gm_inline) no-repeat;
}

6. Use inlined CSS/JS in html by querystring

Like base64, just add ?_gm_inline in url path

<script src="./plugin.js?_gm_inline" type="text/javascript"></script>

<link href="./dialog.css?_gm_inline" rel="stylesheet" type="text/css" >

The inlined sources will be auto updated when source files changed.

7. Use Sprite img in css

Enable Sprite by gulpman.config({ enableCSSSprite: true }), the default is false.
Based on spritesmith, you can transport usemin opts in gulpman.config.
More detail about Spritesmith: https://github.com/Ensighten/spritesmith
Usage: In scss file, just add ?_gm_sprite to img url

.demo {
    background: url(./img/abc.png?_gm_sprite) no-repeat;
    
    /* other style you can set ...*/
    width: 50px;
    height: 50px;
}

8. Use Usemin

You can tranport usemin opts in gulpman.config
More detail about usemin: https://github.com/zont/gulp-usemin
Uage: just add usemin build comments in html. Support js|css|inlinejs|inlinecss syntax
Note: Just write relative path in usemin build comment. Then gulpman can calculate absolute path for assets.
If you don't write output path, the gulpman will combo one new ouput file name automatically.

<!-- build:css ./home.css -->
<link rel="stylesheet" type="text/css" href="./main.css">
<link rel="stylesheet" type="text/css" href="./fff.css">
<!-- endbuild -->


<!-- build:js ../lib/base_lib.js -->
<script type="text/javascript" src="../lib/jquery.js"></script>
<script type="text/javascript" src="../lib/react.js"></script>
<!-- endbuild -->

9. Use js tpl template

Put the .tpl files in your component, and use require or import in ES6, then the tpl files will be packaged in js files.
All tpl will be convertd to text string into js files.
Base64 img and CSS/JS Embed are supported in Tpl

import tpl in es6

    import dialogTpl from './dialog.tpl'

require

    var dialogTpl = require('./dialog.tpl')

10. import css files into js/html

Just import the css, then the gulpman will attach it on page automatically.

import from './style.css';

require('./style.css');

11. Use iconfont convert svg to fontface

Convert SVG to icon-font, use @font-face in css
Run gulp gm:iconfont:install before first running
Put the svg files in components/iconfonts/source directory, then run gulp gm:iconfont to begin start convert
The icon-font and css will generated in iconfonts/gmicon folder

12. Support LAB.js to load async js

Add LAB.js in your project
Use LAB API to load js, use relative path
Example: $LAB.script("../testload/test.js").wait(()=>{console.log('test loaded')})

13. Require CSS in JS

Require css files in your es6/js files
The CSS contents will be packaged into js files, and automatically injected to html when page opend. Using style tag
Should keep the .css extname
Example: require('./style.css') or import style from './style.css'

14. Use karma for Unit Test

Run gulp gm:karma:install before first running, it will install dependencies and generate karma.conf.js.
In your one component folder, create one folder named spec, then put your spec es6 files in the spec folder, the file extname must be .es6
Run gulp gm:karma:start in CLI to start Karma Unit Test, you can view the coverage result in coverage foloder
Set one special spec folder、browsers and other karma options, you can set them in karma.conf.js