@chet.manley/node-project-templates
Templates used by the @chet.manley/create-node-project package.
Releases
- @chet.manley/node-project-templates
Quick Start
Install
⚠️
This package is a dependency of @chet.manley/create-node-project. It is not meant to be a stand-alone project. However, this project can be cloned as a starting point for creating your own custom templates.git clone https://gitlab.com/chet.manley/node-project-templates.git
User Defined Templates
Example Directory Structure
📦 path/to/templates
┣📂 my-template
┃ ┣📂 tmpl
┃ ┃ ┣📂 bin
┃ ┃ ┃ ┗📜 cli
┃ ┃ ┣📜 .gitignore.template
┃ ┃ ┣📜 index.js
┃ ┃ ┣📜 LICENSE
┃ ┃ ┣📜 README.md
┃ ┃ ┗📜 pkg.json
┃ ┗📜 config.json
┣📂 base
┃ ┣📂 files
┃ ┃ ┗ ...
┃ ┗📜 config.json
┣📜 config.json
┗📜 index.js
⚠️
In order to prevent multiplepackage.json
files from being parsed by NPM during publishing (causing many files to be omitted in published package), template package manifest files must be saved under a different name.
Global Templates Configuration
Templates config.js[on]
optional: true
location: root templates directory
{ "defaults": { "manifestFile": "pkg.json", "templateName": "base", "templateFilesDir": "files" } }
key type description defaults object Dictionary of default template options .manifestFile string File name of package manifest .templateName string Template to apply if none is selected .templateFilesDir string Relative path to template files
ℹ️
If this file is omitted,index.js
must be present, and must return an appropriate config object.
Templates index.js
optional: true
location: root templates directory
A synchronous script that returns an object describing your template. Check this project's index.js for an example of how this script should function. The returned object must hold the following shape:
{ config: {}, path: '', templateDirs: [] }
key type description config object Output of config.js[on] path string Absolute path to this templates directory templateDirs array All valid template directories
ℹ️
If this file is omitted,config.js[on]
must be present, and @chet.manley/create-node-project will attempt to manually enumerate templates.
Local Template Configuration
Template config.js[on]
optional: true
location: root of each template directory
{ "dependencyName": "base", "commitTemplate": ".git-commit-template", "far": [ "LICENSE", "README.md" ], "filesDir": "tmpl", "manifestFile": "pkg.json", "name": "My Template", "rename": { ".gitignore.template": ".gitignore", "bin/cli": "{{ project.slug }}" } }
key type description dependencyName string Name of dependent template, or empty string commitTemplate string Path to file containing commit message template far array Files to perform find and replace in filesDir string Path to this template's files manifestFile string File name of package manifest name string Display name of template rename object Dictionary of files to be renamed
ℹ️
If not required by your template, any of the keys may be omitted, or the config file may be omitted entirely.
Dependent Template Name
Defines a template that must be installed before this one, allowing granular template compostion via dependency chains (E.g.,
cli ⇨ cjs ⇨ base
). With the exception of package manifests (which are merged), files in a template overwrite files in a dependency when their names match. While powerful, keep in mind that any missing dependency in the chain will cause the installation to fail.
Commit Message Template
Path to a file containing a commit message template. The contents of this file will be displayed each time a commit is performed in your created projects. Example template can be found in this project's commit template.
Find and Replace
After template files have been copied to the target directory, a simple find and replace is performed. Inside your files, you may use placeholders formatted with double braces (E.g.,
{{ variable }}
), that will be replaced at runtime with the value of the enclosed variable name. If the variable is undefined or cannot be found in the dictionary, the placeholder will be left unaltered.Find and Replace Dictionary
key path value project.description Copy of package.json description
keyproject.name Name of your new project project.namespace Repo namespace, username, or npm scope project.slug Package name minus namespace project.urlPath Namespace+slug as it would appear in repo URL user.email Git user email user.mention Repo username as defined in Git credential config user.name Git user's full name year The current four digit year
Template Files Directory
The location of this template's files. Generally a single subdirectory, you can technically make it multiple subdirectories deep (E.g.,
template/files/here
).
⚠️
This must be a path relative to the config file.
Package Manifest File
A bug/quirk in the way NPM publishes packages causes all
package.json
files in a project to be parsed. This means a template's package manifest must use a different filename, whose contents will be merged into every new project's finalpackage.json
when templates are installed.
Rename
Similar to find and replace, the key:value pairs define files to be renamed after your template's files have been copied to the target directory. The key must be a file path relative to the project root. The value must be either a key path found in the find and replace dictionary, or a filename. If using a filename, include only the filename with no trailing path (all files are renamed in-place). Like find and replace, if a
{{ key.path }}
is provided and cannot be found in the dictionary, the file will remain as-is.
Built with
Contributing
The community is welcome to participate in this open source project. Aspiring contributors should review the contributing guide for details on how to get started. First-time contributors are encouraged to search for issues with the ~"good first issue" label.
License
Copyright © 2020 Chet Manley.