{"id":16055519,"url":"https://github.com/uglow/grunt-modular-project","last_synced_at":"2025-06-27T01:35:15.349Z","repository":{"id":25461326,"uuid":"28891623","full_name":"uglow/grunt-modular-project","owner":"uglow","description":"GruntJS Plugin with configurable-tasks to build modular HTML/CSS/JS source trees, with AngularJS in mind (but SPAs more generally)","archived":false,"fork":false,"pushed_at":"2015-02-25T00:09:52.000Z","size":1100,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-28T07:12:07.147Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uglow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-07T01:08:58.000Z","updated_at":"2017-01-24T02:41:34.000Z","dependencies_parsed_at":"2022-09-04T14:54:06.696Z","dependency_job_id":null,"html_url":"https://github.com/uglow/grunt-modular-project","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fgrunt-modular-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fgrunt-modular-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fgrunt-modular-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fgrunt-modular-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uglow","download_url":"https://codeload.github.com/uglow/grunt-modular-project/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243902293,"owners_count":20366260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-09T02:09:15.671Z","updated_at":"2025-03-18T04:31:14.539Z","avatar_url":"https://github.com/uglow.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [grunt-modular-project](https://github.com/uglow/grunt-modular-project)\n[![npm version](https://badge.fury.io/js/grunt-modular-project.svg)](http://badge.fury.io/js/grunt-modular-project)\n[![devDependency Status](https://david-dm.org/uglow/grunt-modular-project/dev-status.svg)](https://david-dm.org/uglow/grunt-modular-project#info=devDependencies)\n\nGrunt Modular Project is a set of customisable workflow tasks designed for building JS + HTML + CSS modules into a website.\nIt has AngularJS/single-page-apps primarily in-mind.\nThe project transforms a source code folder (`src` by default) into a web-application that can run in development or production mode.\n\n[Change log](CHANGELOG.md)\n\n## Getting Started\nThis plugin requires Grunt `~0.4.5`. The default Karma plugin requires NodeJS `0.12`.\n\nIf you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:\n\n1. Install the plugin\n  ```shell\n  npm install grunt-modular-project --save-dev\n  ```\n\n1. Load the plugin inside your `GruntFile.js`, and decide which workflow tasks you want.\n  ```js\n  grunt.loadNpmTasks('grunt-modular-project');\n  // Use all of the default tasks\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/build');\n  //grunt.loadTasks('node_modules/grunt-modular-project/tasks/buildLibrary'); // This task is only useful if your project is a component/library project.\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/install');\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/optimise');\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/release');\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/serve');\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/unitTest');\n  grunt.loadTasks('node_modules/grunt-modular-project/tasks/verify');\n  ```\n\n1. 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.\n  ```js\n  grunt.initConfig({\n    modularProject: {\n    },\n  });\n  ```\n\n1. 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`](https://github.com/uglow/grunt-modular-project/blob/master/package.json)).\n  ```js\n  // package.json\n  ...\n  \"devDependencies\": {\n      \"colors\": \"^1.0.3\",\n      \"compression\": \"^1.4.1\",\n      \"conventional-changelog\": \"0.0.11\",\n      \"grunt\": \"^0.4.5\",\n      ...\n  }\n  ```\n\n## Example project that uses this plugin\n\n[angular-form-library](https://github.com/uglow/angular-form-lib)\n\n\n### \u003ca name=\"dev\"\u003e\u003c/a\u003e Workflow Tasks\n\nFrom the command line, the following commands are available:\n- `grunt install`: Installs commit message hooks for `git` to support [conventional changelog](https://github.com/ajoslin/conventional-changelog/blob/master/CONVENTIONS.md) \n- `grunt dev`: Continuous development (builds debuggable version into `/dev` folder, starts server, watches files for changes and reloads)\n- `grunt build`: Builds the site into `/dist`, ready for distribution\n- `grunt build:serve`: Builds the site into `/dist`, and then serves it up via a connect webserver\n- `grunt test`: Runs Jasmine unit tests `**/unitTest/*.spec.js` in PhantomJS via Karma\n- `grunt test:browser`: Runs unit tests in Chrome (useful for debugging)\n- `grunt verify:all/src/test`: Checks all/src/test JS code for linting/syntax/style errors\n- `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.\n- `grunt release:minor`: As above, but bumps minor version\n- `grunt release:major`: As above, but bumps major version\n\n\n###Key features###\n- Source code can be (should be) structured into modules\n- No need for \"global\" folders - create a module called `global` or `anythingYouLike` instead\n- Each module can contain:\n  - HTML files, which are deployed to `/views/{module}`\n  - JS files, which are deployed to `/js/{moduleName}.js` . Note that JS files beginning with \"_\" will appear *first* inside the `{moduleName}.js` file.\n  - `/assets`, which contains *static assets* that are deployed to /assets/{module}. Static assets include images, data files which are needed at run-time.\n  - `/docs`, which contains JS and HTML files for component/project documentation. This content is ignored in the production build.\n  - `/includes`, which contains files that should be included into other files at **compile-time**. This folder does not get deployed.\n  - `/styles`, which contains CSS/SASS/LESS/Stylus files that are deployed to `/css`. The technology you use is up to you (currently uses Stylus).\n  - `/unittest`, which contains unit tests (currently Jasmine + Karma, but can be easily changed). This folder does not get deployed.\n  - `/partials`, which contains HTML files that are deployed to `/views/{module}/partials`\n  - **Sub-modules**! Yes, you can create modules-within-modules (like Java packages).\n- Code changes trigger re-compilation (when using `grunt dev`)\n- Support for live-reloading is built-in\n- File-revving (cache-busting) and image+CSS+HTML+JS optimization for production builds\n- 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.\n- Ability to define your own task-wiring from the provided tasks (not locked-in to the default approach)\n- Ability to use special template-tags in HTML pages to refer to `{{vendorScripts}}`, `{{externalScripts}}`, `{{cssFiles}}` and `{{appScripts}}`\n\n\n#### Default Options\nThe default options are located in [modularProject.js](https://github.com/uglow/grunt-modular-project/blob/master/tasks/modularProject.js)\n\n\nThe defaults support the following **input** folder structure:\n\n- config\n  - jscs\n    - .jscsrc\n  - jshint\n    - .jshint\n- src\n  - index.html\n  - modules\n    - **myModule1**\n      - _main.js\n      - other.js\n      - someHtml.html\n      - assets\n        - font\n        - images\n      - include\n      - partials\n        - *.html\n      - style\n        - *.styl\n      - unitTest\n        - *.spec.js\n      - template\n        - componentTemplate.html\n    - **myModule2**\n      - **withSubModule**\n        - assets\n        - unitTest\n        - ...\n      - includes\n      - ... \n\nAnd they produce the following **output** folder when using `grunt dev`:\n- dev\n  - index.html\n  - assets\n    - myModule1\n      - font\n      - images\n  - css\n    - *rootFiles and external CSS files*\n  - js\n    - myModule1.js (contains _main.js THEN all other JS files in the src/modules/module1 folder)\n    - myModule2.js\n    - withSubModule\n      - withSubModule.js\n  - vendor\n    - *any files specified by `buildHTML.compilableVendorJSFiles` and `buildHTML.nonCompilableVendorJSFiles`*\n  - views\n    - myModule1\n      - *.html\n    - myModule2\n      - *.html\n      - withSubModule\n        - *.html\n  \n\nAnd they produce the following **output** folder when using `grunt build`:\n- dist\n  - *as above except all files are revved \u0026 minified \u0026 concatenate where applicable, except:*\n  - js\n    - app.js (all JS files in this folder are concentated and minified into app.js)\n\n\n### Options\n\n#### input.srcDir\nType: `String`\nDefault value: `'src/'`\n\nA relative path from the root directory to the source code root directory.\n\n#### input.modulesDir\nType: `String`\nDefault value: `'src/modules/'`\n\nA relative path from the root directory to the modules directory. It is expected that underneath this directory\nare subdirectories representing one-or-more modules, and that these directories can also contain sub-modules.\n\n*More to come...*\n\n\n### Usage Examples\n\n```js\ngrunt.initConfig({\n  // Configuration to be run (and then tested).\n  modularProject: {\n    input: {\n      // Use the defaults\n    },\n    output: {\n      // Use the defaults\n    },\n    buildCSS: {\n      rootSourceFiles:  ['**/styles/docs.styl', '**/styles/sampleFormStyle.styl'],\n      externalCSSFiles: [\n        '\u003c%= modularProject.bowerDir %\u003eangular-motion/dist/angular-motion.css',\n        '\u003c%= modularProject.bowerDir %\u003ehighlightjs/styles/github.css'\n      ]\n    },\n    buildHTML: {\n      compiledCSSFiles: [\n        'css/angular-motion.css',\n        'css/github.css',\n        'css/docs.css',\n        'css/sampleFormStyle.css'\n      ],\n      compilableVendorJSFiles: [\n        // Order is important - Angular should come first\n        '\u003c%= modularProject.bowerDir %\u003eangular/angular.js',\n        '\u003c%= modularProject.bowerDir %\u003eangular-animate/angular-animate.js',\n        '\u003c%= modularProject.bowerDir %\u003eangular-translate/angular-translate.js',\n        '\u003c%= modularProject.bowerDir %\u003eangular-translate-loader-static-files/angular-translate-loader-static-files.js',\n        '\u003c%= modularProject.bowerDir %\u003eangular-scroll/angular-scroll.js',\n        '\u003c%= modularProject.bowerDir %\u003eangular-strap/dist/angular-strap.js',\n        '\u003c%= modularProject.bowerDir %\u003eangular-strap/dist/angular-strap.tpl.js'\n      ],\n      nonCompilableVendorJSFiles: [\n        '\u003c%= modularProject.bowerDir %\u003ehighlightjs/highlight.pack.js'\n      ]\n    },\n    // Custom config for building a JS library - used by the mpBuildLibrary task\n    buildLibrary: {\n      libFileNamePrefix: 'ng-form-lib',\n      libSrcFiles: ['**/*.js', '!**/docs.js']\n    },\n    release: {\n      // Modify both the docsConfig.json SRC and the temporary documentation version (in /docs), but only commit the SRC version.\n      filesToBump: ['package.json', 'bower.json', 'src/modules/docs/assets/config/docsConfig.json', 'docs/assets/docs/config/docsConfig.json'],\n      filesToCommit: ['package.json', 'bower.json', 'CHANGELOG.md', 'src/modules/docs/assets/config/docsConfig.json'],\n      tasks: ['releaseDocs']\n    },\n    optimise: {\n      tasks: [\n        'mpBuildLibrary',       // New task\n        'clean:optimised',\n        'concurrent:optimisedImages',\n        'copy:optimised',\n        'concat:optimised', 'uglify:optimised',\n        'mpOptimiseHTMLTags', 'targethtml:optimised',\n        'filerev:optimised', 'useminOptimised',\n        'htmlmin:optimised', 'usebanner'\n        'beep:twobits'          // Beep at the end\n      ]\n    },\n    unitTest: {\n      testLibraryFiles: [\n        '\u003c%= modularProject.buildHTML.compilableVendorJSFiles %\u003e',\n        '\u003c%= modularProject.bowerDir %\u003eangular-mocks/angular-mocks.js'\n      ]\n    }\n  }\n});\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n[List of contributors - could be you!](CONTRIBUTORS.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuglow%2Fgrunt-modular-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuglow%2Fgrunt-modular-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuglow%2Fgrunt-modular-project/lists"}