GruntJS Plugin with configurable-tasks to build modular HTML/CSS/JS source trees, with AngularJS in mind (but SPAs more generally)
MIT License
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.
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:
npm install grunt-modular-project --save-dev
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');
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: {
},
});
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",
...
}
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 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 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 versiongrunt release:major
: As above, but bumps major version###Key features###
global
or anythingYouLike
instead/views/{module}
/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
grunt dev
)Gruntfile.js
to make them available to web-pages via the {{vendorScripts}}
template-tag.{{vendorScripts}}
, {{externalScripts}}
, {{cssFiles}}
and {{appScripts}}
The default options are located in modularProject.js
The defaults support the following input folder structure:
And they produce the following output folder when using grunt dev
:
buildHTML.compilableVendorJSFiles
and buildHTML.nonCompilableVendorJSFiles
And they produce the following output folder when using grunt build
:
Type: String
Default value: 'src/'
A relative path from the root directory to the source code root directory.
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...
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'
]
}
}
});
See CONTRIBUTING.md