Conveyal's front-end JavaScript tool-belt. Build, run, lint and deploy front-end code.
With node v6+ and npm 3+ installed:
$ npm install -g mastarm
Mastarm commands can be pointed to a directory containing configuration files using the --config
flag. By default, Mastarm will look in the configurations/default
path of the current working directory. Mastarm currently looks for four different files: env.yml
, settings.yml
, store.yml
, and messages.yml
.
This file should contain strings that can be replaced in front-end JavaScript code using envify
. Example in Scenario Editor.
This file should contain string messages to be used throughout the application. It will replace process.env.MESSAGES
with a string-ified version of the object. Just JSON.parse
it to have access to all of your messages.
Settings contain both Mastarm configuration settings and per environment settings to be used in the application. To override base settings, create an environments section in the yml
file. Example in Modeify. Each section below will contain the settings that they can use.
Not all options pertain to all commands. Entries are in the format input/file.js:output/file.js
.
$ mastarm --help
Usage: mastarm <cmd> [options]
Commands:
build [entries...] [options] Bundle JavaScript & CSS
commit Force intelligent commit messages.
deploy [entries...] [options] Bundle & Deploy JavaScript & CSS
lint [paths...] Lint JavaScript [& CSS coming soon!]
test [options] Run tests using Jest test runner
Options:
-h, --help output usage information
-V, --version output the version number
-c, --config <path> Path to configuration files.
-e, --env <environment> Environment to use.
-m, --minify Minify built files.
-p, --proxy <address> Proxy calls through to target address.
-s, --serve Serve with budo. Auto-matically rebuilds on changes.
-S, --skip-check-dependencies Skip checking and installing out of date package.json dependencies.
-u, --update-snapshots Force update of jest snapshots. USE WITH CAUTION.
-w, --watch Rebuild on changes with watchify.
Compile JS, HTML, CSS, YAML, Markdown into a single .js
. Utilizes babel, browserify, budo, and postcss.
$ mastarm build [options] [entries...]
Options:
-h, --help output usage information
-F, --flyle Cache and serve tiles.
-p, --proxy <address> Proxy calls through to target address.
-s, --serve Serve with budo. Auto-matically rebuilds on changes.
-w, --watch Automatically rebuild on changes.
If no entries are provided, mastarm will attempt to find the entry file. It will first see if the entry
option has been set in the settings.yml
config file. If that setting or the file does not exist, it will attempt to build the file specified as main
in your project's package.json
file. And finally, if both of those options fail, mastarm will attempt to look for the index.js
and index.css
file in the current working directory and attempt to compile each into assets/index.js
and assets/index.css
respectively.
If entries are provided, mastarm will build only those files.
Starting with mastarm 1.0.0, CSS builds will occur separately from the browserify build. Thus, any CSS imports into a JavaScript file will cause a build error. Instead, to build CSS file(s), you must specify the file(s) as entries in the command. Also, when running in serve
or watch
mode, the CSS files will get automatically rebuilt, but a manual page refresh will be necessary.
Utilize best practices when forming a commit message using Commitzen & the Conventional Changelog standard.
Build, push to S3, and invalidate CloudFront in one command.
$ mastarm deploy --help
Usage: deploy [options] [entries...]
Bundle & Deploy JavaScript & CSS
Options:
-h, --help output usage information
--cloudfront CloudFront Distribution ID to invalidate.
--s3bucket S3 Bucket to push to.
Lint using Standard. Everything is passed directly to standard-engine
.
$ mastarm lint [paths...]
You can optionally pass in a directory (or directories) using the glob pattern. Be sure to quote paths containing glob patterns so that they are expanded by standard instead of your shell:
$ mastarm lint "src/util/**/*.js" "test/**/*.js"
Note: by default standard will look for all files matching the patterns: "**/*.js"
, "**/*.jsx"
. Always quote the globs. Needed when used as an npm
command.
Run the Jest test runner on your project. It is expected that you create tests within your project. By default, mastarm will run Jest and generate coverage reports on all .js files in the lib
folder of your project. The patterns
argument will make Jest run only tests whose filename match the provided pattern.
$ mastarm test
Usage: test [options] [patterns...]
Run tests using Jest
Options:
-h, --help output usage information
-u, --update-snapshots Force update of snapshots. USE WITH CAUTION.
--coverage Run Jest with coverage reporting
--no-cache Run Jest with cache
--coverage-paths <paths> Extra paths to collect code coverage from
--setup-files <paths> Setup files to run before each test