template-guide.md

Custom Template Authoring Guide

This guide explains how to create, structure, and organize custom templates for use with @zysam/use-template.

Template Resolution Locations

@zysam/use-template automatically discovers templates in the following order:

1. Built-in Package Templates: Found in the @zysam/use-template package directory (templates/).
2. User Global Templates: Located at ~/.use-template/templates.
3. Local Project Templates: Located in ./templates relative to your current execution directory.
4. Environment Variable: Paths defined in USE_TEMPLATE_DIR (separated by : or ;).
5. Command Option: Directories added dynamically via use-template create -t <path>.

---

Directory Structure of a Template

A template is simply a folder containing starter files for a project.

Recommended Layout

my-templates/
└── my-awesome-template/
    ├── .gitignore
    ├── package.json
    ├── README.md
    ├── tsconfig.json
    └── src/
        └── index.ts

Providing Template Description

If your template contains a package.json with a description field, @zysam/use-template will automatically read and display it in use-template list and interactive selection menus.

Example package.json:

{
  "name": "my-awesome-template",
  "version": "1.0.0",
  "description": "Opinionated TypeScript CLI project template with Vitest and ESLint"
}

---

Ignore Patterns & .gitignore Handling

By default, @zysam/use-template ignores build artifacts and dependencies (node_modules/**, dist/**, .git/**).

If your template directory contains a .gitignore file, @zysam/use-template will parse its rules and convert them to glob patterns. Any matching files in the template directory will not be copied to the new project.

---

Project Name Substitution

When a user creates a new project using use-template create:

1. package.json name: The "name" field in the target project's package.json is updated to the user's chosen project name.
2. README.md: Occurrences of the template name in README.md are replaced with the new project name.
3. isReplaceAll option: If isReplaceAll is enabled (prompted interactively or set in code), all text files matching common extensions (.ts, .tsx, .js, .jsx, .json, .md, .yml, .yaml, .html) will have occurrences of the original template name automatically replaced with the new project name.

---

Example: Creating Your First Custom Template

1. Create a directory in your home folder:

   mkdir -p ~/.use-template/templates/express-api

2. Add project starter files (e.g., package.json, src/index.js, .gitignore).
3. Set the description in package.json:

   {
     "name": "express-api",
     "description": "Minimal Express REST API starter"
   }

4. Test your template:

   use-template list

5. Create a project:

   use-template create