node package manager


node-arjs-builder NPM version

Builder for Angular + RequireJS projects

Install with npm

npm install arjs-builder


Example of application structure. Also see node-projects-config documentations

configs/       * local configs
 ├──admin/     * project
 ├──build/     * bulded projects
 ├──compiled/  * compiled files for local work
 ├──files/     * non included assets
 ├──main/      * project
 └──vendor/    * bower libraries
var gulp = require('gulp');
var arjs = require('arjs-builder')();
gulp.task('test', arjs.test);
gulp.task('default',; //compile and run local servers 

See demo project and big demo project



Return instance of builder


  • localConfigsPath (String)
    Default: process.cwd() + '/configs'
    Folder for local configs.

  • karmaConfigPath (String)
    Default: process.cwd() + '/karma.conf.js' Path to Karma config

  • projectsPath (String)
    Default: process.cwd() + '/projects'
    Root folder for projects etc.

  • configsDir (String)
    Default: '*/_config'
    Glob-pattern for project config folders.

  • compiledDir (String)
    Default: 'compiled'
    Folder for compiled files for local work (styles, compiled vendors)

  • buildDir (String)
    Default: 'build'
    Folder for builded files

  • filesDir (String)
    Default: 'files'
    Assets (big images, fonts, video) which don't include into css-files. Better to store on a separate file server

  • vendorDir (String)
    Default: 'vendor' Vendor libraries (f.e. from bower)

  • moduleIndexFile (String) Default: 'index.js' Name of main module file (in which will be place templates and cache module dependencies)

  • maxListeners (Integer)
    Default: 100
    Set EventEmitter._maxListeners. Increase this value if there are EventEmitter errors of build of big project

  • browsers (Array of String)
    Default: ['chrome >= 35', 'ff >= 20', 'safari >= 7', 'ie >= 10', 'opera >= 12.10', 'android >= 4.4', 'ios >= 7', 'phantomjs >= 1.9']
    Defines supporting browsers. It use for old browsers checking and Autoprefixer

Config API


    public: { ... },
    localhost: {
        webserver: { ... },
        manifest: { ... }
    build: {
        <every module params>
        manifest: { ... },
        modules: { ... },
        copy: { ... }
    vendor: { ... },


Config for web. It will be export to window.project.config

    resources: {
        api: '//my-site/api/v1'


Config for development on local device.


Config for local webserver. May be array of configs for several servers. See node-webserver-lite documentation

    root: 'build',
    port: 7200,
    livereload: true


List of resources which will be included to index.html as link or scripts tags. Paths for builded files add to manifest of builded projects. You can see current project manifest (with extra fields) in window.project. For local and builded project uses different manifests.

//localhost manifest 
    resources: {
        js: [{ //load require.js 
            'src': 'vendor/requirejs/require.js'
            'data-main': 'main/requireconfig'
        css: [
            'compiled/main/vendor/angularStrap.css', //You can include vendor's styles to vendor module or use it directly: 'vendor/bootstrap/dist/css/bootstrap.css' 
//build manifest 
    browsers: [ //you can override default versions of browsers 
        "chrome >= 30",
        "ff >= 20",
        "safari >= 7",
        "ie >= 10",
        "opera >= 12.10",
        "android >= 4.4",
        "ios >= 7",
        "phantomjs >= 1.9"
    resources: {
        html: [
            'main/common/directives/header/template.html', //You can cache some templates, wich will be showed until js-framework loaded 
        css: [
            /* <project styles are added automatically during build of the project> */
        /* js: [<project modules are added automatically during build of the project>] */


Config for build project for final testing and production


copy is a map where keys are Glob-pattern of source files relative to project directory, and values — destination paths or filenames relative to build directory.

//default value of `copy` 
    'favicon.ico': 'favicon.ico', //copy file to build directory 
    'files/**': 'files/' //copy folder to build directory. (`files` is value of `filesDir` option) 

You can add custom files for copying in your config:

    'robots.txt': 'robots.txt'


modules is a map with modules configs. Configs from modules merge on corresponding modules with <every module params>

    //every module params 
    styles: [
        'main/import.styl' //add to each module including vendor and common 
    inlineImgToCss: true,
    includeCss: true,
    uglifyJs: false,
    modules: {
        vendor: {
            //sortIndex: 0, //by default. Vendor loads and runs first 
            includeCss: false
            scripts: [
            styles: [
                'compiled/main/vendor/bootstrap.css' //add vendor style to vendor module 
            uglifyJs: {
                mangle: false //vendor will be uglified 
        common: {
            sortIndex: 1, //Will be load and run second 
            includeCss: false


Has structure like modules. You can compile custom bundles of vendors

    angularStrap: { //module name to compiled directory 
        rev: false, //don't uglify module name 
        templateCacheModule: 'angularStrap',
        root: 'vendor/angular-strap/src',
        includeCss: false //it will create a separate file `angularStrap.css` 
        annotate: {
            createMainModule: 'angularStrap',
            add: true,
            rename: [{
                from: '$tooltip',
                to: '$asTooltip'
        scripts: [
        templates: [
        styles: [ //you can include third-party styles to module 

module params

  • sortIndex (Integer)
    Defines order of modules loading. Use for build.modules array

  • baseUrl (String)
    Default: projectsPath (process.cwd() + '/projects')
    Base path for module files

  • root (String)
    Default: ''
    Path for module files relatively baseUrl

  • index (String)
    Default: false
    Use local index.html. Can be false, true, 'external'. If true or 'external' index.html copy to builded project folder.

    'external' is usually used for server redirects to project folder. Example for admin project:

    localhost config

    localhost: {
      webserver: {
        root: 'build'
        proxies: true
        port: 7201


    location /admin {
      include /etc/nginx/conf.d/auth.conf;
       try_files $uri @admin;
    location @admin {
      rewrite .* /admin/index.html break;
  • system (String)
    Default: 'angularAmd'
    Shorcuts for module wrapper. Can be:

    http: define("<%= name %>", [], function(){ var cache = window.lib.Cache("resource"); <%= contents %> });
    template: define("<%= name %>", [], function(){ var cache = window.lib.Cache("resource"); <%= contents %> });

    http: define("<%= name %>", ["app"], function(app){["$cacheFactory", function($cacheFactory) {var cache = $cacheFactory.get("$http"); <%= contents %> }]); });
    template: define("<%= name %>", ["app"], function(app){["$templateCache", function(cache) {<%= contents %> }]); });

    http: angular.module("<%= name %>").run(["$cacheFactory", function($cacheFactory) {var cache = $cacheFactory.get("$http"); <%= contents %> }]);
    template: angular.module("<%= name %>").run(["$templateCache", function(cache) {<%= contents %> }]);

    or custom wrappers object (<%= name %> is name of http or template cache module)

      http: '<wrapper for http cache>'
      template: '<wrapper for template cache>'

    See gulp-resource-cache config

  • templatePathPrefix (String)
    Default: ''
    Prefix for templates paths

  • httpPathPrefix (String)
    Default: ''
    Prefix for http url paths

  • templateCacheModule (String)
    Name of module with template cache

  • httpCacheModule (String)
    Name of module with http cache

  • wrapScript (String)
    Wrapper for each module script. F.e.:

    vendor: {
      xlsxAmd: {
        rev: false,
        root: 'vendor/js-xlsx/dist',
        wrapScript: 'define(["JSZip"], function(JSZip) {<%= contents %> window.XLSX = XLSX; return XLSX;})',
        scripts: ['xlsx.js']
  • scripts (Array of String)
    Array with paths of projects scripts (js)

  • templates (Array of String)
    Array with paths of projects templates

  • styles (Array of String)
    Array with paths of projects styles

  • httpCache (String)
    Array with urls which will be requested and cached to framework cache. It useful for small resources like languages or city lists

  • templateName (String)
    Default: 'template.html'
    Name of template related to the script

  • styleName (Array of String)
    Default: ['style.css', 'style.styl', 'style.less', 'style.scss', 'style.sass']
    Array names of styles related to the script

  • filesDir (String)
    Default: 'files'
    Name of files folder

  • rev (Boolean)
    Default: true
    Uglify filename to md5 of content

  • uglifyJs (Boolean/Object)
    Default: false
    UglifyJS config

  • minifyHtml (Boolean/Object)
    Default: true ({empty: true, spare: true, loose: true})
    minifyHtml config

  • minifyCss (Boolean/Object)
    Default: false
    minifyCss config

  • autoprefixer (Boolean/Object)
    Default: false
    autoprefixer config

  • includeCss (Boolean)
    Default: true
    Include CSS to JS

  • cssImport (Object)
    Default: {}
    Replace @import on the css content. See cssimport config

  • inlineImgToCss (Boolean/Object)
    Default: true (baseDir: <baseUrl>, maxImageSize: Infinity, exclude: [new RegExp('^[\"\']?((http|https|\/\/)|[.\/]*' + <filesDir> + ')')]) Inline resources to css in base64. See base64 config. Also uou can use extra parameters:

    • excludeFilesStartWith (String or Array) - First path segment of url
    • excludeFilesByRegexp (String or Array) - Filtrating regexp
  • cssUrlPrefix (String) Prefix for resources urls in css

  • stylus (Object)
    Default: {'include-css': true}
    stylus config

  • sass (Object)
    Default: {}
    sass config

  • scss (Object)
    Default: {}
    scss config

  • less (Object)
    Default: {}
    less config

  • annotate (Object)
    Default: {}
    angular annotate config


© Oleg Istomin 2015. Released under the MIT license