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

: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.js[on] | | 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.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 |

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