grunt-modular-project

Grunt Modular Project is a set of customisable workflow tasks designed for building JS + HTML + CSS modules into a website. It has AngularJS/single-page-apps primarily in-mind. The project transforms a source code folder (src by default) into a web-application that can run in development or production mode.

Change log

Getting Started

This plugin requires Grunt ~0.4.5. The default Karma plugin requires NodeJS 0.12.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

1. Install the plugin

npm install grunt-modular-project --save-dev

1. Load the plugin inside your GruntFile.js, and decide which workflow tasks you want.

grunt.loadNpmTasks('grunt-modular-project');
// Use all of the default tasks
grunt.loadTasks('node_modules/grunt-modular-project/tasks/build');
//grunt.loadTasks('node_modules/grunt-modular-project/tasks/buildLibrary'); // This task is only useful if your project is a component/library project.
grunt.loadTasks('node_modules/grunt-modular-project/tasks/install');
grunt.loadTasks('node_modules/grunt-modular-project/tasks/optimise');
grunt.loadTasks('node_modules/grunt-modular-project/tasks/release');
grunt.loadTasks('node_modules/grunt-modular-project/tasks/serve');
grunt.loadTasks('node_modules/grunt-modular-project/tasks/unitTest');
grunt.loadTasks('node_modules/grunt-modular-project/tasks/verify');

1. In your Gruntfile.js, add a section named moduleProject to the data object passed into grunt.initConfig(), and specify any overrides to the default values.

grunt.initConfig({
  modularProject: {
  },
});

1. Modify your package.json file to include the NPM plugin's that your workflow tasks require (refer to node_modules/grunt-modular-project/package.json).

// package.json
...
"devDependencies": {
    "colors": "^1.0.3",
    "compression": "^1.4.1",
    "conventional-changelog": "0.0.11",
    "grunt": "^0.4.5",
    ...
}

Example project that uses this plugin

angular-form-library

Workflow Tasks

From the command line, the following commands are available:

• grunt install: Installs commit message hooks for git to support conventional changelog
• grunt dev: Continuous development (builds debuggable version into /dev folder, starts server, watches files for changes and reloads)
• grunt build: Builds the site into /dist, ready for distribution
• grunt build:serve: Builds the site into /dist, and then serves it up via a connect webserver
• grunt test: Runs Jasmine unit tests **/unitTest/*.spec.js in PhantomJS via Karma
• grunt test:browser: Runs unit tests in Chrome (useful for debugging)
• grunt verify:all/src/test: Checks all/src/test JS code for linting/syntax/style errors
• grunt release: Builds the project, checks that all source code is committed and if so, bumps version numbers in package.json and bower.json (by default), then commits those changes + updated CHANGELOG.md with a version tag.
• grunt release:minor: As above, but bumps minor version
• grunt release:major: As above, but bumps major version

###Key features###

• Source code can be (should be) structured into modules
• No need for "global" folders - create a module called global or anythingYouLike instead
• Each module can contain:
  • HTML files, which are deployed to /views/{module}
  • JS files, which are deployed to /js/{moduleName}.js . Note that JS files beginning with "_" will appear first inside the {moduleName}.js file.
  • /assets, which contains static assets that are deployed to /assets/{module}. Static assets include images, data files which are needed at run-time.
  • /docs, which contains JS and HTML files for component/project documentation. This content is ignored in the production build.
  • /includes, which contains files that should be included into other files at compile-time. This folder does not get deployed.
  • /styles, which contains CSS/SASS/LESS/Stylus files that are deployed to /css. The technology you use is up to you (currently uses Stylus).
  • /unittest, which contains unit tests (currently Jasmine + Karma, but can be easily changed). This folder does not get deployed.
  • /partials, which contains HTML files that are deployed to /views/{module}/partials
  • Sub-modules! Yes, you can create modules-within-modules (like Java packages).
• Code changes trigger re-compilation (when using grunt dev)
• Support for live-reloading is built-in
• File-revving (cache-busting) and image+CSS+HTML+JS optimization for production builds
• Vendor specific libraries such as jQuery can be downloaded via Bower and used by editing Gruntfile.js to make them available to web-pages via the {{vendorScripts}} template-tag.
• Ability to define your own task-wiring from the provided tasks (not locked-in to the default approach)
• Ability to use special template-tags in HTML pages to refer to {{vendorScripts}}, {{externalScripts}}, {{cssFiles}} and {{appScripts}}

Default Options

The default options are located in modularProject.js

The defaults support the following input folder structure:

• config
  • jscs
    • .jscsrc
  • jshint
    • .jshint
• src
  • index.html
  • modules
    • myModule1
      • _main.js
      • other.js
      • someHtml.html
      • assets
        • font
        • images
      • include
      • partials
        • *.html
      • style
        • *.styl
      • unitTest
        • *.spec.js
      • template
        • componentTemplate.html
    • myModule2
      • withSubModule
        • assets
        • unitTest
        • ...
      • includes
      • ...

And they produce the following output folder when using grunt dev:

• dev
  • index.html
  • assets
    • myModule1
      • font
      • images
  • css
    • rootFiles and external CSS files
  • js
    • myModule1.js (contains _main.js THEN all other JS files in the src/modules/module1 folder)
    • myModule2.js
    • withSubModule
      • withSubModule.js
  • vendor
    • any files specified by buildHTML.compilableVendorJSFiles and buildHTML.nonCompilableVendorJSFiles
  • views
    • myModule1
      • *.html
    • myModule2
      • *.html
      • withSubModule
        • *.html

And they produce the following output folder when using grunt build:

• dist
  • as above except all files are revved & minified & concatenate where applicable, except:
  • js
    • app.js (all JS files in this folder are concentated and minified into app.js)

Options

input.srcDir

Type: String Default value: 'src/'

A relative path from the root directory to the source code root directory.

input.modulesDir

Type: String Default value: 'src/modules/'

A relative path from the root directory to the modules directory. It is expected that underneath this directory are subdirectories representing one-or-more modules, and that these directories can also contain sub-modules.

More to come...

Usage Examples

grunt.initConfig({
  // Configuration to be run (and then tested).
  modularProject: {
    input: {
      // Use the defaults
    },
    output: {
      // Use the defaults
    },
    buildCSS: {
      rootSourceFiles:  ['**/styles/docs.styl', '**/styles/sampleFormStyle.styl'],
      externalCSSFiles: [
        '<%= modularProject.bowerDir %>angular-motion/dist/angular-motion.css',
        '<%= modularProject.bowerDir %>highlightjs/styles/github.css'
      ]
    },
    buildHTML: {
      compiledCSSFiles: [
        'css/angular-motion.css',
        'css/github.css',
        'css/docs.css',
        'css/sampleFormStyle.css'
      ],
      compilableVendorJSFiles: [
        // Order is important - Angular should come first
        '<%= modularProject.bowerDir %>angular/angular.js',
        '<%= modularProject.bowerDir %>angular-animate/angular-animate.js',
        '<%= modularProject.bowerDir %>angular-translate/angular-translate.js',
        '<%= modularProject.bowerDir %>angular-translate-loader-static-files/angular-translate-loader-static-files.js',
        '<%= modularProject.bowerDir %>angular-scroll/angular-scroll.js',
        '<%= modularProject.bowerDir %>angular-strap/dist/angular-strap.js',
        '<%= modularProject.bowerDir %>angular-strap/dist/angular-strap.tpl.js'
      ],
      nonCompilableVendorJSFiles: [
        '<%= modularProject.bowerDir %>highlightjs/highlight.pack.js'
      ]
    },
    // Custom config for building a JS library - used by the mpBuildLibrary task
    buildLibrary: {
      libFileNamePrefix: 'ng-form-lib',
      libSrcFiles: ['**/*.js', '!**/docs.js']
    },
    release: {
      // Modify both the docsConfig.json SRC and the temporary documentation version (in /docs), but only commit the SRC version.
      filesToBump: ['package.json', 'bower.json', 'src/modules/docs/assets/config/docsConfig.json', 'docs/assets/docs/config/docsConfig.json'],
      filesToCommit: ['package.json', 'bower.json', 'CHANGELOG.md', 'src/modules/docs/assets/config/docsConfig.json'],
      tasks: ['releaseDocs']
    },
    optimise: {
      tasks: [
        'mpBuildLibrary',       // New task
        'clean:optimised',
        'concurrent:optimisedImages',
        'copy:optimised',
        'concat:optimised', 'uglify:optimised',
        'mpOptimiseHTMLTags', 'targethtml:optimised',
        'filerev:optimised', 'useminOptimised',
        'htmlmin:optimised', 'usebanner'
        'beep:twobits'          // Beep at the end
      ]
    },
    unitTest: {
      testLibraryFiles: [
        '<%= modularProject.buildHTML.compilableVendorJSFiles %>',
        '<%= modularProject.bowerDir %>angular-mocks/angular-mocks.js'
      ]
    }
  }
});

Contributing

See CONTRIBUTING.md

List of contributors - could be you!