A package of Grunt tasks and configuration to use with Dojo 2 Packages.
This package contains configuration and tasks for Grunt to help orchestrate development of Dojo 2 Packages. It is meant to be a development dependency of a Dojo 2 package.
To install:
$ npm install grunt-dojo2 --save-dev
The package Gruntfile.js should look like this:
module.exports = function (grunt) {
require('grunt-dojo2').initConfig(grunt);
};This repository uses prettier for code styling rules and formatting. A pre-commit hook is installed automatically and configured to run prettier against all staged files as per the configuration in the projects package.json.
An additional npm script to run prettier (with write set to true) against all src and test project files is available by running:
npm run prettierThere are several peer dependencies which you should have installed in the containing project:
| Package | SemVer |
|---|---|
| codecov.io | >=0.1.6 |
| dts-generator | >=1.7.0 |
| grunt-contrib-clean | >=1.0.0 |
| grunt-contrib-copy | >=1.0.0 |
| grunt-contrib-watch | >=1.0.0 |
| grunt-text-replace | >=0.4.0 |
| grunt-typings | >=0.1.4 |
| grunt-ts | >=5.0.0 |
| grunt-tslint | >=3.0.0 |
| remap-istanbul | >=0.6.3 |
If you need to customise the Grunt configuration, you can do so by passing a second argument
to the initConfig() function. For example to configure Uglify2, you would do something
like this:
module.exports = function (grunt) {
grunt.loadNpmTasks('grunt-contrib-uglify');
require('grunt-dojo2').initConfig(grunt, {
uglify: {
dist: {
options: {
sourceMap: true,
sourceMapName: 'dist/umd/_debug/module.min.js.map',
sourceMapIncludeSources: true,
sourceMapIn: 'dist/umd/_debug/module.js.map',
compress: {
dead_code: true,
unsafe: true
}
},
files: {
'dist/umd/module.min.js': 'dist/umd/module.js'
}
}
}
});
grunt.registerTask('dist', grunt.config.get('distTasks').concat('uglify:dist'));
};The grunt tslint task, runs tslint with the following configuration.
options: {
configuration: grunt.file.readJSON('tslint.json')
},
src: {
src: [
'<%= all %>',
'!typings/**/*.ts',
'!tests/typings/**/*.ts',
'!node_modules/**/*.ts'
]
}
The grunt dojo-ts task runs a project through the TypeScript compiler using the project's tsconfig.json. It is preconfigured with two targets, dev and dist.
The dev target transpiles a project for development. src/ and test/ files are built and the output is put in the _build directory.
The dist target prepares a project for distribution and applies the following overrides to the tsconfig:
{
compilerOptions: {
outDir: distDirectory,
declaration: true
},
exclude: ['tests/**/*.ts']
}
Where the distDirectory is defaulted to dist/umd.
If you have other root level directories besides src and tests, you might want to exclude them from the dist build. Including them can cause unwanted output in your dist/umd directory. For example, if you wanted to exclude an examples directory, you would add:
ts: {
dist: {
exclude: ['tests/**/*.ts', 'examples/**/*.ts'],
}
}It is possible to create custom targets for the ts by adding an entry to the grunt config, such as:
"ts": {
"custom": {
"compilerOptions": {
"target": "es6",
"module": "commonjs"
}
}
}
The custom ts config can be run using grunt grunt-ts:custom.
The intern task provides multiple preconfigured targets
options: {
runType: 'runner',
config: '<%= devDirectory %>/tests/intern',
reporters: [ 'Runner' ]
},
browserstack: {},
saucelabs: {
options: {
config: '<%= devDirectory %>/tests/intern-saucelabs'
}
},
remote: {},
local: {
options: {
config: '<%= devDirectory %>/tests/intern-local',
}
},
node: {
options: {
runType: 'client'
}
},
proxy: {
options: {
proxyOnly: true
}
}
The doc task is used to automatically build and publish API documentation to the project's GitHub pages. Please note
that if you want to generate documentation locally by manually running this command use the grunt typedoc command
instead.
Running grunt typedoc (part of grunt doc) will only generate APIs using typedoc. In order to
automatically commit or publish API documentation the DEPLOY_DOCS environment variable must be set to either
publish or commit. Environment variables are used so they may be turned on/off using travis-ci settings and to
support forks that may want to use the travis build, but do not want to automatically publish documentation.
To support continuous delivery of API documents to your project's GitHub pages Travis-ci needs access to your GitHub repository. This is best achieved by supplying an encrypted deployment key that can be used via SSH (there are other methods that are less secure that we will not go into). To use this method you will need to:
- Create a ssh key; e.g.
ssh-keygen -t rsa -C "[email protected]" - encrypt the private key using travis cli; e.g.
travis encrypt-file deploy_key(you will need to be logged in and be the owner of the GitHub repository to do this) - add the public key under your project's GitHub settings
- add
grunt doc --publish-apias part of yourinstallsteps
The link task is designed to ease the local development and testing of changes that span multiple packages. Traditionally npm link can be used but this assumes that the project structure is the same as the distribution, which for dojo2 projects is not the case.
This command emulates the behaviour of npm link but with some additional steps to ensure that the linked structure matches that of the distributed package.
Once grunt link has been run within a dojo2 package, npm link can be used as normal to created the linked package dependency.
Example
npm link dojo-widgetsThe release task automates all the steps involved in building, tagging and publishing a dojo2 package.
grunt release --pre-release-tag=alphanote:
- Task runs the
distpipelines as a prerequisite. - Requires being logged into NPM unless using the
dry-runoptions
#####Options
The pre-release-tag is required, the other options are all optional.
pre-release-tag- determines the pre-release tag used for the published version (usuallyalpha,betaorrc)dry-run- performs the release in dry run mode, no commits, tags or publishing occur. The generated package is built into thedistdirectory.initial- indicates that it is an initial release of an asset and therefore assumes the version rather than usingnpm veiw.skip-checks- skips checks against the registered maintainers, only available withdry-runpush-back- automatically pushes back to github (tags and commits)tag- the npm tag to publish as (defaults tonext)
The running grunt dev will execute the dev pipeline which as follows:
clean:typingstypingstslintclean:devts:devcopy:staticTestFiles
The running grunt dist will execute the dist pipeline which as follows:
clean:typingstypingstslintclean:distts:dist
Running grunt doc will execute the doc pipeline, which comes from the docTasks configuration:
clean:typingstypings:devtypedocclean:typedocclean:ghpages
The running grunt test will execute the test pipeline which as follows:
clean:coveragedevintern:noderemapIstanbul:coverageclean:coverage
Running grunt will execute the default pipeline which as follows:
cleandev
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent