gulp-imprint
v0.1.1
Published
Set of configurable gulp tasks to release and publish nodejs apps and libraries
Downloads
1,398
Readme
gulp-imprint
Set of configurable and opinionated gulp tasks to release and publish nodejs-based apps and libraries. This set of tasks was designed for complex build and release processes involving many steps as one would have developing plugins and modules for Angular 2+ framework. gulp-imprint is an overkill for simple libraries.
WARNING: gulp-imprint is set to clean build and package output directories before building the project. If you specify your source code directory as either build or package directory, your source code WILL BE WIPED!
Installation
$ npm i gulp-imprint --save-dev
Understanding gulp-imprint
To fully understand how gulp-imprint works and why it works this way, it is important to understand some of terminology used in this documentation.
Glossary
Bump - version number increase according to semver rules. Only MAJOR, MINOR and PATCH are supported at the moment.
Build task - a task or set of tasks to build/transpile the source code into publishable format.
Build dir - directory containing the result of build task.
Source code - source code of an application or library, which will be built to become a package.
Package - a set of files ready to be uploaded into npm-compatible registry.
Package dir - directory containing package.
Package file - package.json which will be published as part of package.
Source package file - package.json used to describe source code and its dependencies.
Overlay - set of static files and directories which will be copied into package dir over build files.
Release - a task to bump package version and tag it in git.
Publish - a task to publish package into npm-compatible registry.
Typical workflow
High level workflow includes only three steps: release
, package
and publish
. Here's the breakdown of each step.
Release
- Prepare - gulp-imprint will switch to
master
branch and pull the latest changes. - Bump - gulp-imprint will bump package version according to semver rules.
- Tag - gulp-imprint will commit changes to
package.json
tomaster
branch and will create a tag.
Package
- Clean - gulp-imprint will clean both build and package output directories.
- Build - gulp-imprint will run build task/sequence as defined in its configuration.
- Prepare - gulp-imprint will copy built files into package directory.
- Overlay - gulp-imprint will copy over contents of overlay set into package directory.
Publish
- Publish to npm - gulp-imprint will run
$ npm publish
inside package folder.
Why such workflow?
Publishing complex libraries using transpilers requires additional steps like transpiling, separate dependency management between source code and resulting package, running tests, adding static files like documentation, etc. gulp-imprint enforces separation of different layers of application/library to make this process easier to manage. This set of tasks is also CI friendly as you can use them to automate your workflows.
gulp-imprint itself is using this process to publish itself to npm. Please take a look at project structure to understand it better.
Available tasks
imprint:patch
,imprint:minor
,imprint:major
- creates a new release and publishes it by running the following sequence of tasks:imprint:release:X
,imprint:package
,imprint:npm:publish
.imprint:package
- creates a package by running the following sequence of tasks:imprint:clean
,imprint:package:build
,imprint:package:prepare
,imprint:package:overlay
.imprint:clean
- cleans build and package output directories.imprint:package:prepare
- prepares package output directory by copying contents of build directory.imprint:package:overlay
- copies overlay files and directories over contents inside package directory.imprint:package:build
- runs build tasks as specified by configuration (buildSequence
).imprint:npm:publish
- runs$ npm publish
inside package output folder.imprint:bump:major
,imprint:bump:minor
,imprint:bump:patch
- bumps package version according to semver rules.imprint:release:patch
,imprint:release:minor
,imprint:release:major
- creates a release by running the sequence of tasks:imprint:release:git:X
,imprint:bump:X
,imprint:release:git:X
.imprint:release:git:prepare
- prepares repository for release by switching tomaster
branch and pulling latest changes.imprint:release:git:tag
- commitspackage.json
changes, creates a new tag and pushes everything toorigin
.
Configuration
The following structure describes possible configuration options and their default values:
{
buildDir: './dist/out', // Directory containing transpiled output
packageDir: './dist/package', // Directory which will contain all the files ready to be pushed to npm registry
cleanBuildDir: true, // Set to true to clean buildDir before running build task
cleanPackageDir: true, // Set to true to clean packageDir before running build task
overlays: ['./package/**', './README.md', 'LICENSE'], // Set of files and directories to overlay into packageDir
packageFile: './package/package.json', // Location of package.json which will be published as part of npm package
buildSequence: null, // Set of gulp tasks to execute as part of build process
dryRun: false, // gulp-imprint will print out git commands instead of running them if set to true
commitPrefix: 'Version ' // Prefix for commit messages
};
Basic usage
Just run one of the imprint:X
tasks where X is either major
, minor
or patch
:
$ gulp imprint:minor
Skip publishing to npm
If your project should not be published to npm registry (for example, you're building end-user application, not a library)
then run release
and package
manually:
$ gulp imprint:release:X
$ gulp imprint:package
where X is either major
, minor
or patch
.