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.
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:
- Install the plugin
npm install grunt-modular-project --save-dev
- Load the plugin inside your
GruntFile.js
, and decide which workflow tasks you want.
grunt;// Use all of the default tasksgrunt;//grunt.loadTasks('node_modules/grunt-modular-project/tasks/buildLibrary'); // This task is only useful if your project is a component/library project.grunt;grunt;grunt;grunt;grunt;grunt;
- In your
Gruntfile.js
, add a section namedmoduleProject
to the data object passed intogrunt.initConfig()
, and specify any overrides to the default values.
grunt;
- Modify your
package.json
file to include the NPM plugin's that your workflow tasks require (refer tonode_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
Workflow Tasks
From the command line, the following commands are available:
grunt install
: Installs commit message hooks forgit
to support conventional changeloggrunt 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 distributiongrunt build:serve
: Builds the site into/dist
, and then serves it up via a connect webservergrunt test
: Runs Jasmine unit tests**/unitTest/*.spec.js
in PhantomJS via Karmagrunt 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 errorsgrunt release
: Builds the project, checks that all source code is committed and if so, bumps version numbers inpackage.json
andbower.json
(by default), then commits those changes + updatedCHANGELOG.md
with a version tag.grunt release:minor
: As above, but bumps minor versiongrunt 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
oranythingYouLike
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).
- HTML files, which are deployed to
- 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
- jscs
- 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
- ...
- withSubModule
- myModule1
And they produce the following output folder when using grunt dev
:
- dev
- index.html
- assets
- myModule1
- font
- images
- myModule1
- 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
andbuildHTML.nonCompilableVendorJSFiles
- any files specified by
- views
- myModule1
- *.html
- myModule2
- *.html
- withSubModule
- *.html
- myModule1
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;
Contributing
See CONTRIBUTING.md