template-kit

Library for creating projects from templates.

Features

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 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

Installation

npm install template-kit --save

Example

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: '[email protected]:appcelerator/template-kit-test.git',
        dest: '/path/to/new/project'
    });

    console.log('Project created successfully!');
})();

Template Specification

Structure

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 they do, template-kit will happily call npm install after generation.

Any file that is not binary will be treated as an 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 TemplateEngine 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 the corresponding value in the data 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 meta.js file. If there are multiple project templates, then you can present them by using the prompts mechanism.

Metadata

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.
data	`Object`	Arbitrary data to mix in with the `run()` data and pass into `ejs` when copying a text file.
filters	`Array.<String>`	An array of file patterns to copy. The patterns follow the gitignore rules.
prompts	`Object`	An array of prompt descriptors that is used to select the template and template data.
template	`String`	Relative path to the template files. Defaults to `'.'`

API

`TemplateEngine`

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

Constructor

`new TemplateEngine(opts)`

Initializes the template engine.

Param	Type	Description
[opts]	`Object`	Various options.
[opts.requestOptions]	`Object`	`got` HTTP client options and proxy/security settings below.
[opts.requestOptions.caFile]	`String`	A path to a PEM-formatted certificate authority bundle.
[opts.requestOptions.certFile]	`String`	A path to a client cert file used for authentication.
[opts.requestOptions.keyFile]	`String`	A path to a private key file used for authentication.
[opts.requestOptions.proxy]	`String`	A proxy server URL. Can be `http` or `https`.
[opts.requestOptions.strictSSL]	`Boolean`	When falsey, disables TLS/SSL certificate validation for both `https` requests and `https` proxy servers.

Methods

`.run(opts)` ⇒ `Promise`

Builds a project based on the specified template and options.

Param	Type	Description
opts	`Object`	Various options
[opts.data]	`Object`	A data object that is passed into `ejs` when copying template files.
opts.dest	`String`	The destination directory to create the project in.
[opts.filters]	`Set` \| `Array.<String>`	A list of file patterns to pass into `micromatch` when copying files.
[opts.force]	`Boolean`	When `true`, overrides the destination if it already exists.
[opts.git=true]	`Boolean`	When `true` and `git` executable is found, after the the project is generated, initialize a git repo in the project directory.
[opts.npmArgs]	`Array.<String>`	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.
opts.src	`String`	The path to a directory, archive file, globally installed npm package, archive URL, npm package name, or git repo.
[opts.template='.']	`String`	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 various stages. The contents of the state depends on the Source Type.

Property	Type	Description
dest	`String`	The destination directory to create the project in.
destFile	`String`	When copying files, this is the destination file path.
disposables	`Array.<String>`	A list of temp directories to cleanup.
extractDest	`String`	The temporary directory where the archive was extracted to.
filters	`Set` \| `Array.<String>`	A list of file patterns to copy.
force	`Boolean`	When `true`, overrides the destination if it already exists.
git	`Boolean`	When `true` and `git` executable is found, after the the project is generated, initialize a git repo in the project directory.
gitInfo	`Object`	The parsed git repo information.
npmArgs	`Array.<String>`	An array of additional parameters to pass into npm. Useful if you need to add extra arguments for things such as skipping shrinkwrap.
npmManifest	`Object`	The npm package information
prompts	`Array.<Object>`	A list of prompt descriptors.
src	`String`	The path to a directory, archive file, globally installed npm package, archive URL, npm package name, or git repo.
srcFile	`String`	When copying files, this is the source file path.
template	`String`	Relative path to the directory containing the template files. Defaults to `'.'`

Events

The TemplateEngine emits several events. It uses the 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()`.
[async next(opts)]	`Function`	Continue to next hook.

engine.on('init', async opts => {
    // before the run state has been initialized
});

or

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.
args	`Array.<String>`	The arguments passed into the `git` command.
opts	`Object`	`spawn()` options.
[async next(opts)]	`Function`	Continue to next hook.

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.
[async next(opts)]	`Function`	Continue to next hook.

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.
[async next(opts)]	`Function`	Continue to next hook.

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.
file	`String`	The name of the file being extracted.

engine.on('extract-file', async (state, file) => {
    console.log(`Extracting ${file}`);
});

`#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.
percent	`Number`	The percentage complete.

engine.on('extract-progress', async (state, percent) => {
    console.log(`Extracted ${percent}%`);
});

`#npm-download`

Emitted when downloading and extracting an npm package.

Source Type: npm

Param	Type	Description
state	`Object`	The run state.
[async next(opts)]	`Function`	Continue to next hook.

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.
[async next(opts)]	`Function`	Continue to next hook.

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.
[async next(opts)]	`Function`	Continue to next hook.

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.

engine.on('prompt', async state => {
    // prompt for `state.prompts` 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.
[async next(opts)]	`Function`	Continue to next hook.

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.
[async next(opts)]	`Function`	Continue to next hook.

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.
cmd	`String`	The path to npm command.
args	`Array.<String>`	The npm arguments.
opts	`Object`	`spawn()` options.
[async next(opts)]	`Function`	Continue to next hook.

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.
args	`Array.<String>`	`git` arguments.
opts	`Object`	`spawn()` options.
[async next(opts)]	`Function`	Continue to next hook.

engine.on('git-init`', async (state, args, opts, next) => {
    // 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.
[async next(opts)]	`Function`	Continue to next hook.

engine.on('cleanup`', async (state, next) => {
    // before temp directories have been deleted
    await next();
    // after cleanup
});

Legal

This project is open source under the Apache Public License v2 and is developed by Axway, Inc and the community. Please read the LICENSE file included in this distribution for more information.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
src		src
test		test
.eslintrc		.eslintrc
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
Jenkinsfile		Jenkinsfile
LICENSE		LICENSE
README.md		README.md
gulpfile.js		gulpfile.js
package.json		package.json
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

template-kit

Features

Installation

Example

Template Specification

Structure

Metadata

API

`TemplateEngine`

Constructor

`new TemplateEngine(opts)`

Methods

`.run(opts)` ⇒ `Promise`

Run State

Events

`#init`

`#git-clone`

`#download`

`#extract`

`#extract-file`

`#extract-progress`

`#npm-download`

`#create`

`#load-meta`

`#prompt`

`#copy`

`#copy-file`

`#npm-install`

`#git-init`

`#cleanup`

Legal

About

Releases 1

Packages

Languages

License

appcelerator/template-kit

Folders and files

Latest commit

History

Repository files navigation

template-kit

Features

Installation

Example

Template Specification

Structure

Metadata

API

TemplateEngine

Constructor

new TemplateEngine(opts)

Methods

.run(opts) ⇒ Promise

Run State

Events

#init

#git-clone

#download

#extract

#extract-file

#extract-progress

#npm-download

#create

#load-meta

#prompt

#copy

#copy-file

#npm-install

#git-init

#cleanup

Legal

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

`TemplateEngine`

`new TemplateEngine(opts)`

`.run(opts)` ⇒ `Promise`

`#init`

`#git-clone`

`#download`

`#extract`

`#extract-file`

`#extract-progress`

`#npm-download`

`#create`

`#load-meta`

`#prompt`

`#copy`

`#copy-file`

`#npm-install`

`#git-init`

`#cleanup`

Packages