npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

grunt-yomb

v0.4.12

Published

YOM builder

Downloads

9

Readme

YOM Builder

YOM builder is a tool for packaging AMD modules, compiling micro templates and optimizing html files.

Installation

Firstly you need to install nodejs and npm, then install grunt with command npm install -g grunt as we use grunt to run yomb tasks. At last use command npm install grunt-yomb --save-dev to install our builder.

Conventions

Too many configarations bring in complexity and is hard to maintain, so we make some conventions to ease our work.
We use "(example)" or "(dist, src)" to show an example. "src" links to source files, and "dist" links to built result files.

  • JS file of which name is "main" or end with "-main", "_main", ".main" is the target building file. For example, "main.js", "index-main.js", "index_main.js" and "index.main.js" are target building files (dist, src).
  • Dependancy module with relative path will be packaged with target building file. This process is recursive, which means if "main" requires "./foo", and "./foo" requires "./bar", then "main", "./foo" and "./bar" will be packaged together. var foo = require('./foo');
    var bar = require('../bar');
    var vender = require('vender');
    foo and bar will be packaged with target building file (dist, src).
    If the output file is in the same folder, the output file names are "main-built.js", "index-main-built.js", "index_main_built.js" and "index.main.built.js" in order not to overwrite the orignal files, or else the output file name is the same as the target building file (example).
  • Html file of which name is end with '.tpl' is micro template file. This file will be built into AMD module file. For example, you have a file named "cargo-list.tpl.html", and you can require it as below.
    var cargoListTmpl = require('./cargo-list.tpl.html');
    Then you can use it as below.
    $('cargo-list').innerHTML = cargoListTmpl.render(data);
    As JS file, html file of which name is "main.tpl" or end with "-main.tpl", "_main.tpl", ".main.tpl" will be built into AMD module file. For example, "foo-main.tpl.html" will be built into "foo-main.tpl.html.js" (dist, src).
  • less file of which name is "main" or end with "-main", "_main", ".main" will be built into css file. For example, "foo-main.less" will be built into "foo-main.css" (dist, src).

Require AMD modules in template

As templates will be built into AMD modules, they can also require other AMD modules.

<%
var $ = require('jquery');
var fooTpl = require('./foo.tpl.html');
%>
<%=fooTpl.render($data)%>

Write AMD module like nodejs module

You can write your client AMD module like writing a nodejs module, yomb will build it into a formalized AMD module. You must assign your module implementation to module.exports (dist, src).

var $ = require('jquery');
var foo = {};
foo.bar = function() {
  alert('hello world');
};
module.exports = foo;

will be built into

define(['require', 'exports', 'module', 'jquery'], function(require, exports, module) {
  var $ = require('jquery');
  var foo = {};
  foo.bar = function() {
    alert('hello world');
  };
  module.exports = foo;
});

Use variables in requiring module name

var langFoo = require('lang/{{G.LANG}}/foo');
var foo = {};
foo.bar = function() {
  alert(langFoo.hello);
};
module.exports = foo;

will be built into

define(['require', 'exports', 'module', 'lang/' + G.LANG + '/foo'], function(require, exports, module) {
  var langFoo = require('lang/' + G.LANG + '/foo');
  var foo = {};
  foo.bar = function() {
    alert(langFoo.hello);
  };
  module.exports = foo;
});

Usage

Firstly you need to create a Gruntfile.js file (example) in the root filder of your project. Then add a "yomb" task in grunt file, then add some targets in yomb task. The name of a target should be start with "coffee-", "build-", "concat-" or "copy-". You can run yomb task with command grunt yomb.

  • coffee- : compile coffeescript file into javascript file (dist, src).
  • build- : build AMD module, micro template or html source file.
  • concat- : concat one or multiple files into one file.
  • copy- : copy files. YOM builder is built on NodeJS. You can run it in command line like this:
    node path/to/builder.js In "coffee-" and "build-" targets, you can set "ignore" property to ignore some folders or files.
'coffee-all': {
  files: [
    {
      src: 'src',
      ignore: {
        'node_modules': 1
      }
    }
  ]
},
'build-all': {
  files: [
    {
      src: 'src',
      dest: 'dist',
      ignore: {
        'node_modules': 1,
        'script/vender/jquery/jquery.js': 1
      }
    }
  ]
},

Command line options

  • --config-file filepath : In general builder does't need config file to work, It does traversal building in current working directory according to the rules. However, you can specify a config file to use advanced setting.
  • --uglify N : YOM builder use uglifyJS to compress JS code. N stands for compress level, default is 0.
    -1: beautify
    0 : do nothing
    1 : uglify
    2 : mangle
    3 : squeeze
  • --cssmin : YOM builder use cssmin to compress CSS code. Pass this if you want to compress CSS file.
  • --compressHtml : YOM builder use google htmlcompressor to compress HTML code. Pass this if you want to compress HTML file.
  • --compress-html-options : Options passed to htmlcompressor.
  • --build-node-tpl : Pass this if you want to build micro template file into nodeJS module file.
  • --exclude filelist : Relative file path list delimited by comma. Used to exclude files built with target building file.
  • --output-base-path : If this was specified, all the output path will be joined with thie base path.

yomb task options

  • uglify : Same as uglify option in command line.
    eg. {"uglify": -1}
  • cssmin : Same as cssmin option in command line.
    eg. {"cssmin": true}
  • compressHtml : Same as compress-html option in command line.
    eg. {"compressHtml": true}
  • outputBasePath : Same as output-base-path option in command line.
    eg. {"outputBasePath": "../static}
  • buildNodeTpl : Same as build-node-tpl option in command line.
    eg. {"buildNodeTpl": true}
  • exclude : Same as exclude option in command line, and has higher priority, but is a hash object.
    eg. {"exclude" : {"./mod1": 1, "../mod2": 1}}
  • copyright : JS copyright text.
    eg. {"copyright": "/* All rights reserved */"}
  • properties : This option defines reusable values.
    eg. {"properties": {"a": {"b": {"c": 1}}}}
    Defined values can be used as %{{a.b.c}}% in html source file and template.
    "_lang_" is a special property, it is the language code being processed. You can use %{{_lang_}}% in html source file to include language resource file.
    eg. <!-- include "lang/%{{_lang_}}%/foo.js" -->
  • lang : Multiple language support.
    • base : The path where language resource files placed. Language resource file should be AMD module file.
      eg. {"lang": {"base": "./js/lang"}}

Optimize html file

YOM builder can build external JS and CSS file into Html file, in order to enhance the page performance by reducing http request amount. Html file of which name is end with ".src" is considerred the source file to be optimized, and the optimized result file will be output to the output folder with the name without ".src". Micro template file can also be optimized in this way. Below are instructions of optimization. Html file of which name is end with ".inc" is reusable html segment file, which can be included in the source file (dist, src).

  • include : Include an external file into the Html source file, the included file can also be Html source file, and the optimization is done recursively.
    eg. <!-- include "./mod1.js" -->, <!-- include "./segment.inc.html" -->
    You can even specify a plain-id to the instruction, in order to make the JS code not execuded immediately, and execude it on demand.
    eg. <!-- include "./mod1.js" plain-id:mod1-script -->
    The output will be <script type="text/plain" id="mod1-script">... You can also use include in template file to mixin another template.
    eg. <!-- include "./foo.tpl.html" -->
  • require : Require is an instruction for building AMD module into Html source file. It also supports plain-id.
    eg. <!-- require "./mod1" -->
  • uglify : Uglify JS code built into Html source file.
    eg. <!-- uglify -1 -->
  • cssmin : Compress CSS code built into Html source file.
    eg. <!-- cssmin true -->

Use language resource in html source file

Language resource can be used as ${{a.b.c}}$ in html source file If you have a language resource file "lang/en/foo.js" as below.

define({
  label: {
    bar: 'Bar'
  } 
});

You can use ${{foo.label.bar}}$ in html source file.

Examples

https://github.com/webyom/grunt-yomb-example