simple-scaffold 3.1.0 → 3.1.1

package/README.md

@@ -28,196 +28,292 @@ of files you're generating.
 
 ---
 
-## Documentation
+> **Full documentation is available at
+> [chenasraf.github.io/simple-scaffold](https://chenasraf.github.io/simple-scaffold)** — including
+> detailed guides on [CLI usage](https://chenasraf.github.io/simple-scaffold/docs/usage/cli),
+> [Node.js API](https://chenasraf.github.io/simple-scaffold/docs/usage/node),
+> [templates](https://chenasraf.github.io/simple-scaffold/docs/usage/templates),
+> [configuration files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files),
+> [examples](https://chenasraf.github.io/simple-scaffold/docs/usage/examples), and
+> [migration from v1/v2](https://chenasraf.github.io/simple-scaffold/docs/usage/migration).
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Configuration Files](#configuration-files)
+- [Templates](#templates)
+- [Interactive Mode & Inputs](#interactive-mode--inputs)
+- [Remote Templates](#remote-templates)
+- [CLI Reference](#cli-reference)
+- [Node.js API](#nodejs-api)
+- [Built-in Helpers](#built-in-helpers)
+- [Contributing](#contributing)
 
-See full documentation [here](https://chenasraf.github.io/simple-scaffold).
+## Getting Started
 
-- [Command Line Interface (CLI) usage](https://chenasraf.github.io/simple-scaffold/docs/usage/cli)
-- [Node.js usage](https://chenasraf.github.io/simple-scaffold/docs/usage/node)
-- [Templates](https://chenasraf.github.io/simple-scaffold/docs/usage/templates)
-- [Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files)
-- [Migration](https://chenasraf.github.io/simple-scaffold/docs/usage/migration)
+### Install
 
-## Getting Started
+```sh
+npm install -D simple-scaffold
+# or use directly with npx
+npx simple-scaffold
+```
 
-### Quick Start
+### Initialize a Project
 
-The fastest way to get started is to run `init` in your project directory:
+Run `init` to create a config file and an example template:
 
 ```sh
 npx simple-scaffold init
 ```
 
-This creates a `scaffold.config.js` and an example template in `templates/default/`. Then generate
-files with:
+This creates `scaffold.config.js` and `templates/default/{{name}}.md`. Now generate files:
 
 ```sh
 npx simple-scaffold MyProject
 ```
 
-### Cheat Sheet
+### One-off Usage (No Config)
 
-A quick rundown of common usage scenarios:
+Generate files from a template directory without a config file:
 
-- Remote template config file on GitHub:
+```sh
+npx simple-scaffold -t templates/component -o src/components MyComponent
+```
 
-  ```sh
-  npx simple-scaffold -g username/repository -c scaffold.js -k component NewComponentName
-  ```
+## Configuration Files
 
-- Local template config file:
+Config files let you define reusable scaffold definitions. Simple Scaffold **auto-detects** config
+files in the current directory — no `--config` flag needed.
 
-  ```sh
-  npx simple-scaffold -c scaffold.js -k component NewComponentName
-  ```
+It searches for these files in order:
 
-- Local one-time usage:
+`scaffold.config.{mjs,cjs,js,json}`, `scaffold.{mjs,cjs,js,json}`, `.scaffold.{mjs,cjs,js,json}`
 
-  ```sh
-  npx simple-scaffold -t templates/component -o src/components NewComponentName
-  ```
+### Example
 
-### Remote Configurations
+```js
+// scaffold.config.js
+module.exports = {
+  component: {
+    templates: ["templates/component"],
+    output: "src/components",
+  },
+  page: {
+    templates: ["templates/page"],
+    output: "src/pages",
+    subdir: true,
+  },
+}
+```
 
-The fastest way to get started is to is to re-use someone else's (or your own) work using a template
-repository.
+Then run:
 
-A remote config can be loaded in one of these ways:
+```sh
+npx simple-scaffold -k component MyComponent
+npx simple-scaffold -k page Dashboard
+```
 
-- For templates hosted on GitHub, the syntax is `-g user/repository_name`
-- For other Git platforms like GitLab, use `-g https://example.com/user/repository_name.git`
+Use the key `default` to skip the `-k` flag entirely.
 
-These remote configurations support multiple scaffold groups, which can be specified using the
-`--key` or `-k` argument:
+### Listing Available Templates
 
 ```sh
-$ npx simple-scaffold \
-  -g chenasraf/simple-scaffold \
-  -k component \
-  PageWrapper
-
-# equivalent to:
-$ npx simple-scaffold \
-  -g https://github.com/chenasraf/simple-scaffold.git \
-  -c scaffold.config.js \
-  -k component \
-  PageWrapper
+npx simple-scaffold list
+npx simple-scaffold list -c path/to/config.js
 ```
 
-By default, the template name is set to `default` when the `--key` option is not provided.
+## Templates
 
-See information about each option and flag using the `--help` flag, or read the
-[CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli). For information
-about how configuration files work, [see below](#configuration-files).
+Templates are regular files in a directory. Both **file names** and **file contents** support
+Handlebars syntax. Simple Scaffold preserves the directory structure of your template folder.
 
-### Interactive Mode
+### Example Template
 
-When running in a terminal, Simple Scaffold will interactively prompt for any missing required
-values — name, output directory, template paths, and template key (if multiple are available).
+`templates/component/{{pascalCase name}}.tsx`
 
-Config files can also define **inputs** — custom fields that are prompted interactively and become
-template data:
+```tsx
+// Created: {{ now 'yyyy-MM-dd' }}
+import React from "react"
 
-```js
-module.exports = {
-  component: {
-    templates: ["templates/component"],
-    output: "src/components",
-    inputs: {
-      author: { message: "Author name", required: true },
-      license: { message: "License", default: "MIT" },
-    },
-  },
+export default {{ pascalCase name }}: React.FC = (props) => {
+  return (
+    <div className="{{ camelCase name }}">{{ pascalCase name }} Component</div>
+  )
 }
 ```
 
-Inputs can be pre-provided via `--data` or `-D` to skip the prompt:
+Running `npx simple-scaffold -t templates/component -o src/components PageWrapper` produces
+`src/components/PageWrapper.tsx` with all tokens replaced.
 
-```sh
-npx simple-scaffold -c scaffold.config.js -k component -D author=John MyComponent
+### Glob Patterns & Exclusions
+
+Template paths support globs and negation:
+
+```js
+{
+  templates: ["templates/component/**", "!templates/component/README.md"]
+}
 ```
 
-### Configuration Files
+### .scaffoldignore
 
-You can use a config file to more easily maintain all your scaffold definitions. Simple Scaffold
-**auto-detects** config files in the current directory — no `--config` flag needed.
+Place a `.scaffoldignore` file in your template directory to exclude files. It works like
+`.gitignore` — one pattern per line, `#` for comments.
 
-It searches for these files in order: `scaffold.config.{mjs,cjs,js,json}`,
-`scaffold.{mjs,cjs,js,json}`, `.scaffold.{mjs,cjs,js,json}`.
+## Interactive Mode & Inputs
 
-`scaffold.config.js`
+When running in a terminal, Simple Scaffold prompts for any missing required values (name, output,
+template key). Config files can also define **inputs** — custom fields that are prompted
+interactively:
 
 ```js
 module.exports = {
-  // use "default" to avoid needing to specify key
-  // in this case the key is "component"
   component: {
     templates: ["templates/component"],
     output: "src/components",
-    data: {
-      // ...
+    inputs: {
+      author: { type: "text", message: "Author name", required: true },
+      license: { type: "select", message: "License", options: ["MIT", "Apache-2.0", "GPL-3.0"] },
+      isPublic: { type: "confirm", message: "Public package?" },
+      priority: { type: "number", message: "Priority level", default: 1 },
     },
   },
 }
 ```
 
-Then just run from the same directory:
+**Input types:** `text` (default), `select`, `confirm`, `number`
+
+Pre-fill inputs from the command line to skip prompts:
 
 ```sh
-$ npx simple-scaffold PageWrapper
-# or explicitly: npx simple-scaffold -c scaffold.config.js PageWrapper
+npx simple-scaffold -k component -D author=John -D license=MIT MyComponent
 ```
 
-This will allow you to avoid needing to remember which configs are needed or to store them in a
-one-liner in `package.json` which can get pretty long and messy, and harder to maintain.
-
-Also, this allows you to define more complex scaffolds with logic without having to use the Node.js
-API directly. (Of course you always have the option to still do so if you wish)
-
-More information can be found at the
-[Configuration Files documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files).
+## Remote Templates
 
-### Templates Structure
+Use templates from any Git repository:
 
-Templates are **any file** in the a directory given to `--templates`.
+```sh
+# GitHub shorthand
+npx simple-scaffold -g username/repo -k component MyComponent
 
-Simple Scaffold will maintain any file and directory structure you try to generate, while replacing
-any tokens such as `{{ name }}` or other custom-data using
-[Handlebars.js](https://handlebarsjs.com/).
+# Full Git URL (GitLab, Bitbucket, etc.)
+npx simple-scaffold -g https://gitlab.com/user/repo.git -k component MyComponent
+```
 
-`templates/component/{{ pascalName name }}.tsx`
+The repository is cloned to a temporary directory, used, and cleaned up automatically.
+
+## CLI Reference
+
+### Commands
+
+| Command       | Description                              |
+| ------------- | ---------------------------------------- |
+| `[name]`      | Generate files from a template (default) |
+| `init`        | Create config file and example template  |
+| `list` / `ls` | List available template keys in a config |
+
+### Options
+
+| Flag                           | Short     | Description                                          | Default     |
+| ------------------------------ | --------- | ---------------------------------------------------- | ----------- |
+| `--config`                     | `-c`      | Path to config file or directory                     | auto-detect |
+| `--git`                        | `-g`      | Git URL or GitHub shorthand                          |             |
+| `--key`                        | `-k`      | Template key from config                             | `default`   |
+| `--output`                     | `-o`      | Output directory                                     |             |
+| `--templates`                  | `-t`      | Template file paths or globs                         |             |
+| `--data`                       | `-d`      | Custom JSON data                                     |             |
+| `--append-data`                | `-D`      | Key-value data (`key=string`, `key:=raw`)            |             |
+| `--subdir`/`--no-subdir`       | `-s`/`-S` | Create parent directory with input name              | `false`     |
+| `--subdir-helper`              | `-H`      | Helper to transform subdir name                      |             |
+| `--overwrite`/`--no-overwrite` | `-w`/`-W` | Overwrite existing files                             | `false`     |
+| `--dry-run`                    | `-dr`     | Preview output without writing files                 | `false`     |
+| `--before-write`               | `-B`      | Script to run before each file is written            |             |
+| `--after-scaffold`             | `-A`      | Shell command to run after scaffolding               |             |
+| `--quiet`                      | `-q`      | Suppress output                                      |             |
+| `--log-level`                  | `-l`      | Log level (`none`, `debug`, `info`, `warn`, `error`) | `info`      |
+| `--version`                    | `-v`      | Show version                                         |             |
+| `--help`                       | `-h`      | Show help                                            |             |
+
+## Node.js API
 
-```tsx
-// Created: {{ now 'yyyy-MM-dd' }}
-import React from 'react'
-
-export default {{pascalCase name}}: React.FC = (props) => {
-  return (
-    <div className="{{camelCase name}}">{{pascalCase name}} Component</div>
-  )
-}
+```js
+import Scaffold from "simple-scaffold"
+
+// Basic usage
+const scaffold = new Scaffold({
+  name: "MyComponent",
+  templates: ["templates/component"],
+  output: "src/components",
+})
+await scaffold.run()
+
+// Load from config file
+const scaffold = await Scaffold.fromConfig("scaffold.config.js", {
+  key: "component",
+  name: "MyComponent",
+})
+await scaffold.run()
 ```
 
-To generate the template output once without saving a configuration file, run:
-
-```sh
-# generate single component
-$ npx simple-scaffold \
-  -t templates/component \
-  -o src/components \
-  PageWrapper
+### Config Options
+
+| Option          | Type                       | Description                           |
+| --------------- | -------------------------- | ------------------------------------- |
+| `name`          | `string`                   | Name for generated files (required)   |
+| `templates`     | `string[]`                 | Template paths or globs (required)    |
+| `output`        | `string \| Function`       | Output directory or per-file function |
+| `data`          | `Record<string, unknown>`  | Custom template data                  |
+| `inputs`        | `Record<string, Input>`    | Interactive input definitions         |
+| `helpers`       | `Record<string, Function>` | Custom Handlebars helpers             |
+| `subdir`        | `boolean`                  | Create parent directory with name     |
+| `subdirHelper`  | `string`                   | Helper for subdir name transformation |
+| `overwrite`     | `boolean \| Function`      | Overwrite existing files              |
+| `dryRun`        | `boolean`                  | Preview without writing               |
+| `logLevel`      | `string`                   | Log verbosity                         |
+| `beforeWrite`   | `Function`                 | Async hook before each file write     |
+| `afterScaffold` | `Function \| string`       | Hook after all files are written      |
+
+## Built-in Helpers
+
+All helpers work in both file names and file contents.
+
+### Case Helpers
+
+| Helper       | Example Input | Output    |
+| ------------ | ------------- | --------- |
+| `camelCase`  | `my name`     | `myName`  |
+| `pascalCase` | `my name`     | `MyName`  |
+| `snakeCase`  | `my name`     | `my_name` |
+| `kebabCase`  | `my name`     | `my-name` |
+| `hyphenCase` | `my name`     | `my-name` |
+| `startCase`  | `my name`     | `My Name` |
+| `upperCase`  | `my name`     | `MY NAME` |
+| `lowerCase`  | `My Name`     | `my name` |
+
+### Date Helpers
+
+```handlebars
+{{now "yyyy-MM-dd"}}
+{{now "yyyy-MM-dd HH:mm" -1 "hours"}}
+{{date myDateVar "yyyy-MM-dd"}}
+{{date "2077-01-01T00:00:00Z" "yyyy-MM-dd" 7 "days"}}
 ```
 
-This will immediately create the following file: `src/components/PageWrapper.tsx`
+### Custom Helpers
 
-```tsx
-// Created: 2077-01-01
-import React from 'react'
+Add your own via config:
 
-export default PageWrapper: React.FC = (props) => {
-  return (
-    <div className="pageWrapper">PageWrapper Component</div>
-  )
+```js
+module.exports = {
+  component: {
+    templates: ["templates/component"],
+    output: "src/components",
+    helpers: {
+      shout: (str) => str.toUpperCase() + "!!!",
+    },
+  },
 }
 ```
 
@@ -231,7 +327,7 @@ just a small amount to help sustain this project, I would be very very thankful!
   <img
     height='36'
     src='https://cdn.ko-fi.com/cdn/kofi1.png?v=3'
-    alt='Buy Me a Coffee at ko-fi.com' 
+    alt='Buy Me a Coffee at ko-fi.com'
   />
 </a>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-scaffold",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Generate any file structure - from single components to entire app boilerplates, with a single command.",
   "homepage": "https://chenasraf.github.io/simple-scaffold",
   "repository": {
@@ -59,7 +59,7 @@
     "@inquirer/select": "^5.1.2",
     "date-fns": "^4.1.0",
     "glob": "^13.0.6",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "massarg": "2.1.1",
     "minimatch": "^10.2.4",
     "zod": "^4.3.6"
@@ -67,16 +67,16 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.2",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
     "mock-fs": "^5.5.0",
     "prettier": "^3.8.1",
     "rimraf": "^6.1.3",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1",
-    "vite": "^8.0.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
     "vite-node": "^6.0.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   }
 }