strong-build
v2.1.2
Published
Prepare a node package for deployment
Downloads
612
Readme
strong-build
Build a node application package, preparing it for deploy to production.
It is useful standalone, but is commonly used to build applications for deployment to the StrongLoop process manager, strong-pm.
For more details, see http://strong-pm.io.
Installation
sl-build
is made available through the
strongloop tool as slc build
, and
works well with the StrongLoop Process Manager,
strong-pm.
sl-build
can be installed standalone with:
npm install -g strong-build
Overview
The purpose of building a node application is to bundle its dependencies so that there:
- are no deploy-time dependencies on external services
- it is in a deployable format
The build process is implemented as four commands:
sl-build --install
: the core of the build, it installs dependencies, runs custom build steps, and prunes development dependenciessl-build --bundle
: modify the npmpackage.json
and.npmignore
configuration files so dependencies will be packedsl-build --pack
: create an npm package of the buildsl-build --commit
: commit the build onto a git branch
The default behaviour of sl-build
depends on whether the current directory is
a git repository.
- In a git repository: the default is
sl-build --install --commit
, to build onto a git branch. - Otherwise: the default is
sl-build --bundle --install --pack
, to build an npm package.
Both npm packages and git branches can be deployed to the StrongLoop process manager using the StrongLoop deploy tool.
Specifying any command disables the default, and allows any mix of commands to be run, either singly, or all at once.
Also, note that builds should be done in a clean working copy. You don't
build deployment artifacts out of a possibly dirty working copy if you want
reproducible builds. You can clean your working copy using git clean -x -d
-f
. This is too destructive for the build tool to do, but doing a build in an
unclean working repository may trigger an error in a future version of the
tool.
install command
Installation automates the common work flow for building application dependencies:
npm install --ignore-scripts
: Install dependencies without running scripts. Scripts can be run optionally with--scripts
.npm run build
: Custom build steps such asgrunt build
orbower
can be specified in the package'sscripts.build
property, since front-end code served by node commonly requires some amount of preparation.npm prune --production
: Remove development-only tools (such as bower, or grunt) that may have been required by the package's build scripts, but should not be deployed.
Note that compilation and install scripts should be run on the deployment server using:
npm rebuild
: Compile add-ons for current system.npm install
: Run any install scripts (not typical, but if they exist they may be required to prepare the application for running).
If builds are done on the same system architecture as the deploy, it is possible to compile and package the add-ons, and avoid the presence of a compiler on the deployment system. This is recommended when possible, but is not the default assumption of strong-build.
bundle command
Bundling configures the package.json and .npmignore so deployment (not
development) dependencies as well as any 'build' script output will not be
ignored by npm pack
.
This is unnecessary when using git to deploy, but mandatory when creating npm packages!
package.bundleDependencies
Bundling requires that the bundleDependencies
property in the package.json
file is configured to include all non-development dependencies, including
optional dependencies, which are often overlooked.
Its important that you remember to add every new production dependency to the
bundleDependencies
property, if you don't, npm will try and install them
after deploy, creating unexpected and fragile dependencies on npmjs.org.
Since keeping this up-to-date manually is likely to go wrong, we recommend
allowing the bundle command to do this for you. However, the
bundleDependencies
property is not modified if present, so you are free to
maintain it yourself, if you wish (or to not just the bundle command).
.npmignore
Setting bundle dependencies is insufficient to get the output of build tools.
Both build output and project ephemera such as test output is usually ignored
using .gitignore
, as it should be. However, if npm does not find a
.npmignore
configuration file, it uses .gitignore
as a fallback. This means
that if you have custom build output, such as minimized JavaScript, it will be
treated as project ephemera, and not be packed by npm.
The bundle command will create an empty .npmignore
file if there is a
.gitignore
file but there is no .npmignore
file. This will work for clean
repositories, but if you have any project ephemera, they will get packed.
We recommend you write and maintain you own .npmignore
file unless your build
process guarantees a clean working repository.
pack command
Pack output is a tar file in the format produced by npm pack
and
accepted by npm install
and
strong-deploy.
The pack file is placed in the parent directory of the application being packed, to avoid the pack file itself getting packed by future builds, and to allow the working repository to be cleaned.
If a .npmignore
file was created by the bundle command, check the pack file
contents carefully to ensure build products are packed, but project ephemera are
not.
commit command
Committing build products into git provides the most robust tracking and storage, including versioning of deployments.
This is often done by committing both build products and dependencies
(node_modules
) into git where they pollute the source branches, create massive
git commits and huge churn on the development branches and repositories.
The commit command does not do this.
It commits an exact replica of current branch source and build products onto a deployment branch. After the commit, the deployment branch tip shows as a merge of the deployment and source branches. This allows a complete history of deployment builds to be kept in git, but separated from the development branches. Deployment branches can be pushed to the same repository as the development branches, or not.
Note that branches prepared like this can also be pushed to platforms such as OpenShift and Heroku.
The default name of the deployment branch is "deploy", but is configurable with
the --onto BRANCH
modifier to the commit command.
Usage
usage: sl-build [options]
Build a node application package.
With no options, the default depends on whether a git repository is
detected or not.
If a git repository is detected the default is `--git`: install and commit the
build results to the "deploy" branch, which will be created if it does not
already exist.
If no git repository is detected the default is `--npm`: bundle, install, and
pack the build results into a `<package-name>-<version>.tgz` file.
Options:
-h,--help Print this message and exit.
-v,--version Print version and exit.
-n,--npm Same as `--install --bundle --pack`.
-g,--git Same as `--install --commit`.
-i,--install Install dependencies (without scripts, by default).
--scripts If installing, run scripts (to build addons).
-b,--bundle Modify package to bundle deployment dependencies.
-p,--pack Pack into a publishable archive (with dependencies).
Git specific options:
-c,--commit Commit build output (branch specified by --onto).
--onto BRANCH Branch to commit build results to, created if
necessary ("deploy", by default).
License
strong-build uses a dual license model.
You may use this library under the terms of the Artistic 2.0 license, or under the terms of the StrongLoop Subscription Agreement.