@chet.manley/node-project-templates v1.0.5

@chet.manley/node-project-templates

Templates used by the @chet.manley/create-node-project package.

Releases

• @chet.manley/node-project-templates
  • Releases
  • Quick Start
    • Install
  • User Defined Templates
    • Example Directory Structure
    • Global Templates Configuration
      • Templates config.js[on]
      • Templates index.js
    • Local Template Configuration
      • Template config.js[on]
        • Dependent Template Name
        • Commit Message Template
        • Find and Replace
        • Template Files Directory
        • Package Manifest File
        • Rename
  • Built with
  • Contributing
  • License

Quick Start

Install

:warning:\ 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

:warning:\ In order to prevent multiple package.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.json

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

:information_source:\ 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.json
path	string	Absolute path to this templates directory
templateDirs	array	All valid template directories

:information_source:\ 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.json

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

:informationsource:\ _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 key
project.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).

:warning:\ 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 final package.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.