Project template toolkit
npm install template-kit[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Deps][david-image]][david-url]
[![Dev Deps][david-dev-image]][david-dev-url]
Library for creating projects from templates.
* Project generation using local template as a directory, archive file, or globally installed npm package
* Download templates from git, npm, or a URL to a archive file
* Support for .zip, .gz, .bz2, .tar, tar.gz, tar.bz2, .tgz, and .tbz2 archives
* Run text files through [ejs][ejs] during file copy
* JavaScript lifecycle hooks
* User-defined copy file inclusion/exclusion filters
* Data-driven destination directory and filenames
* npm dependency installation
* git repository initialization
npm install template-kit --save
``javascript
import TemplateEngine from 'template-kit';
(async () => {
const engine = new TemplateEngine();
engine.on('create', async (state, next) => {
console.log('Creating the project from the template');
await next();
console.log('Project created!');
});
await engine.run({
src: 'git@github.com:appcelerator/template-kit-test.git',
dest: '/path/to/new/project'
});
console.log('Project created successfully!');
})();
`
A template can be an empty directory or a massive collection of files and subdirectories. All of
the files in the template can be compressed in a single archive file (.zip, .tgz, etc) for
distribution.
Templates do _not_ need to be npm packages and they do _not_ need to have a package.json. If theynpm install
do, template-kit will happily call after generation.
Any file that is _not_ binary will be treated as an [ejs][ejs] template regardless of extension.
ejs templates have access to any variable or function in the data object including the opts.data
passed into the constructor, the data export from the meta.js, or any
data that has be injected via a hook.
Directories and filenames may contain a {{variable}} sequence which will be replaced with thedata
corresponding value in the object.
By default, template-kit will treat the root of the template directory as the actual template.
However, the template may contain several project templates or place all of the template files in
a single subdirectory. The relative project template path is defined by setting the template
property in the file. If there are multiple project templates, then you can present them
by using the prompts mechanism.
template-kit will load the template's metadata from a meta.js file or the package's "main" file.
The metadata can be an object or an async function that returns an object. The object contains the
following properties:
| Property | Type | Description |
| -------- | ---------------- | ----------- |
| complete | Function | A function to call after the project generation is complete. Useful for displaying post create steps. |Object
| data | | Arbitrary data to mix in with the run() data and pass into ejs when copying a text file. |Array.
| filters | | An array of file patterns to copy. The patterns follow the gitignore rules. |Object
| prompts | | An array of prompt descriptors that is used to select the template and template data. |String
| template | | Relative path to the template files. Defaults to '.' |
Resolves a template source, installs the template, and manages the install lifecycle.
* new TemplateEngine(opts)
* _methods_
* .run(opts)
* _inherited from HookEmitter_ ➚
* .on(event, listener) ➚
* .once(event, listener) ➚
* .off(event, listener) ➚
* _events_
* #init
* #git-clone
* #download
* #extract
* #extract-file
* #extract-progress
* #npm-download
* #create
* #load-meta
* #prompt
* #copy
* #copy-file
* #npm-install
* #git-init
* #cleanup
#### new TemplateEngine(opts)
Initializes the template engine.
| Param | Type | Description |
| ------------------------------- | --------- | ------------------------------------------------------------ |
| [opts] | Object | Various options. |Object
| [opts.requestOptions] | | got HTTP client options and proxy/security settings below. |String
| [opts.requestOptions.caFile] | | A path to a PEM-formatted certificate authority bundle. |String
| [opts.requestOptions.certFile] | | A path to a client cert file used for authentication. |String
| [opts.requestOptions.keyFile] | | A path to a private key file used for authentication. |String
| [opts.requestOptions.proxy] | | A proxy server URL. Can be http or https. |Boolean
| [opts.requestOptions.strictSSL] | | When falsey, disables TLS/SSL certificate validation for both https requests and https proxy servers. |
#### .run(opts) ⇒ Promise
Builds a project based on the specified template and options.
| Param | Type | Description |
| ------------------- | ------------------------- | --------------- |
| opts | Object | Various options |Object
| [opts.data] | | A data object that is passed into ejs when copying template files. |String
| opts.dest | | The destination directory to create the project in. |Set
| [opts.filters] | \| Array. | A list of file patterns to pass into micromatch when copying files. |Boolean
| [opts.force] | | When true, overrides the destination if it already exists. |Boolean
| [opts.git=true] | | When true and git executable is found, after the the project is generated, initialize a git repo in the project directory. |Array.
| [opts.npmArgs] | | An array of additional parameters to pass into npm. Useful if you need to add extra arguments for things such as skipping shrinkwrap or production only. |String
| opts.src | | The path to a directory, archive file, globally installed npm package, archive URL, npm package name, or git repo. |String
| [opts.template='.'] | | Relative path to the directory containing the template files. This value overrides the default template from the meta.js, but not the template value returned from prompting. |
##### Run State
Every time run() is invoked, a new state object is created and passed through the variousstate
stages. The contents of the depends on the Source Type.
| Property | Type | Description |
| ----------- | ------------------------- | ------------------------------------------------------------ |
| dest | String | The destination directory to create the project in. |String
| destFile | | When copying files, this is the destination file path. |Array.
| disposables | | A list of temp directories to cleanup. |String
| extractDest | | The temporary directory where the archive was extracted to. |Set
| filters | \| Array. | A list of file patterns to copy. |Boolean
| force | | When true, overrides the destination if it already exists. |Boolean
| git | | When true and git executable is found, after the the project is generated, initialize a git repo in the project directory. |Object
| gitInfo | | The parsed git repo information. |Array.
| npmArgs | | An array of additional parameters to pass into npm. Useful if you need to add extra arguments for things such as skipping shrinkwrap. |Object
| npmManifest | | The npm package information |Array.
| prompts |
The TemplateEngine emits several events. It uses the [hook-emitter][hook-emitter] package which
supports async event listeners.
Some events are only emitted depending on the source type (e.g. the src passed into run()).
`
Event Flow ┌───────┐
│ run() │
└───┬───┘ ┌───────┐
├─────┤ #init │
│ └───────┘
┌──────────────┬───────────┼────────┬──────────┬──────────┐
git URL Local Local Global npm
│ ┌─────┴─────┐ File Directory npm Package │
│ │ #download │ │ │ │ │
│ └─────┬─────┘ │ │ │ │
┌─────┴──────┐ └─────┬─────┘ │ │ ┌───────┴───────┐
│ #git-clone │ ┌─────────┴─────────┐ │ │ │ #npm-download │
└─────┬──────┘ │ #extract │ │ │ └───────┬───────┘
│ │ #extract-file │ │ │ │
│ │ #extract-progress │ │ │ │
│ └─────────┬─────────┘ │ │ │
└────────────────────┴───────┬──────┴──────────┴──────────┘
┌─────┴──────┐
│ #load-meta │
└─────┬──────┘ ┌─────────┐
├────────┤ #prompt │
┌────┴────┐ └─────────┘
│ #create │
└────┬────┘ ┌───────┐
├────────┤ #copy │
│ └───┬───┘ ┌────────────┐
│ └────────┤ #copy-file │
│ ┌──────────────┐ └────────────┘
├────┤ #npm-install │
│ └──────────────┘
│ ┌───────────┐
├────┤ #git-init │
│ └───────────┘
┌────┴─────┐
│ #cleanup │
└──────────┘
#### #init
Initialize the run state with the options passed into run().
Source Type: Local file, local directory, global npm package, npm, git, URL
| Param | Type | Description |
| ------------------ | ---------- | -------------------------------- |
| opts | Object | The options passed into run(). |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('init', async opts => {
// before the run state has been initialized
});
or
`javascript`
engine.on('init', async (opts, next) => {
// before the run state has been initialized
await next();
// after initialization
});
#### #git-clone
Emitted when git clone is called.
Source Type: git
| Param | Type | Description |
| ------------------ | ---------------- | -------------------------------------------- |
| state | Object | The run state. |Array.
| args | | The arguments passed into the git command. |Object
| opts | | spawn() options. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('git-clone', async (state, args, opts, next) => {
// before the git clone call
await next();
// after the clone
});
#### #download
Emitted when downloading a file based on a http/https URL.
Source Type: URL
| Param | Type | Description |
| ------------------ | ---------- | ---------------------- |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('download', async (state, next) => {
// before the download begins
await next();
// after the clone
});
#### #extract
Emitted when extracting the downloaded or local archive file.
Source Type: Local directory, URL
| Param | Type | Description |
| ------------------ | ---------- | ---------------------- |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('extract', async (state, next) => {
// before the archive is extracted
await next();
// after extraction
});
#### #extract-file
Emits the current file being extracted from the archive.
Source Type: Local directory, URL
| Param | Type | Description |
| ------------------ | ---------- | ------------------------------------- |
| state | Object | The run state. |String
| file | | The name of the file being extracted. |
`javascriptExtracting ${file}
engine.on('extract-file', async (state, file) => {
console.log();`
});
#### #extract-progress
Emits the current progress of the file extraction from 0 to 100.
Source Type: Local directory, URL
| Param | Type | Description |
| ------------------ | ---------- | ------------------------ |
| state | Object | The run state. |Number
| percent | | The percentage complete. |
`javascriptExtracted ${percent}%
engine.on('extract-progress', async (state, percent) => {
console.log();`
});
#### #npm-download
Emitted when downloading and extracting an npm package.
Source Type: npm
| Param | Type | Description |
| ------------------ | ---------- | ---------------------- |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('npm-download', async (state, next) => {
// before downloading and extracting the npm package
await next();
// after extraction
});
#### #create
Emitted when about to populate the destination directory.
Source Type: All sources.
| Param | Type | Description |
| ------------------ | ---------- | ---------------------- |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('create', async (state, next) => {
// before the project is generated
await next();
// after project is generated
});
#### #load-meta
Emitted when attempting to load the template's meta.js or "main" file.
Source Type: Any source with a meta script.
| Param | Type | Description |
| ------------------ | ---------------- | ------------------------ |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('load-meta', async (state, next) => {
// before npm dependencies have been installed
await next();
// after installation
});
#### #prompt
Allows application opportunity to prompt for missing data, then populate state's data property.
Source Type: Any source with a meta script.
| Param | Type | Description |
| ------------------ | ---------- | -------------------------------------- |
| state | Object | The run state. |
`javascriptstate.prompts
engine.on('prompt', async state => {
// prompt for and store results in state.data
});
#### #copy
Emitted when copying the template files to the destination.
Source Type: All sources.
| Param | Type | Description |
| ------------------ | ---------- | ------------------------------------ |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('copy', async (state, next) => {
// before copying has begun
await next();
// after files have been copied
});
#### #copy-file
Emitted for each file copied.
Source Type: All sources.
| Param | Type | Description |
| ------------------ | ---------- | ----------------------------------- |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('copy-file', async (state, next) => {
// before a specific file is to be copied
await next();
// file has been copied
});
#### #npm-install
Emitted when installing npm dependencies in the destination directory.
Source Type: Any source with a package.json.
| Param | Type | Description |
| ------------------ | ---------------- | ------------------------ |
| state | Object | The run state. |String
| cmd | | The path to npm command. |Array.
| args | | The npm arguments. |Object
| opts | | spawn() options. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript`
engine.on('npm-install', async (state, cmd, args, opts, next) => {
// before npm dependencies have been installed
await next();
// after installation
});
#### #git-init
Emitted when a git repository is being initialized in the project directory.
Source Type: Any source.
| Param | Type | Description |
| ------------------ | ---------------- | ---------------------- |
| state | Object | The run state. |Array.
| args | | git arguments. |Object
| opts | | spawn() options. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript', async (state, args, opts, next) => {
engine.on('git-init
// before the git repo has been initialized
await next();
// after initialization
});
``
#### #cleanup
Emitted after the project has been created and the temp directories are to be deleted.
Source Type: Any source.
| Param | Type | Description |
| ------------------ | ---------- | ---------------------- |
| state | Object | The run state. |Function
| [async next(opts)] | | Continue to next hook. |
`javascript', async (state, next) => {
engine.on('cleanup
// before temp directories have been deleted
await next();
// after cleanup
});
``
This project is open source under the [Apache Public License v2][1] and is developed by
Axway, Inc and the community. Please read the [LICENSE`][1] file included
in this distribution for more information.
[1]: https://github.com/appcelerator/template-kit/blob/master/LICENSE
[npm-image]: https://img.shields.io/npm/v/template-kit.svg
[npm-url]: https://npmjs.org/package/template-kit
[downloads-image]: https://img.shields.io/npm/dm/template-kit.svg
[downloads-url]: https://npmjs.org/package/template-kit
[david-image]: https://img.shields.io/david/appcelerator/template-kit.svg
[david-url]: https://david-dm.org/appcelerator/template-kit
[david-dev-image]: https://img.shields.io/david/dev/appcelerator/template-kit.svg
[david-dev-url]: https://david-dm.org/appcelerator/template-kit#info=devDependencies
[ejs]: https://www.npmjs.com/package/ejs
[hook-emitter]: https://www.npmjs.com/package/hook-emitter