gulpman

Create Modular Front-End Build System. Based on gulp, very easy and light

Usage no npm install needed!

<script type="module">
  import gulpman from 'https://cdn.skypack.dev/gulpman';
</script>

README

Coverage Status


NPM version Build status

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 gulpgulp-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 libglobal 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

Tutorial

Tutorial Link

License

MIT