scaffolder

README

Scaffolder

A generic, powerful scaffolding engine for creating projects from templates. It supports interactive variables, conditional logic, and various step types, all defined in a simple YAML configuration.

Installation

go install github.com/dajooo/scaffolder@latest

Usage

Create a new project from a template:

scaffolder new <path-to-template-directory>

Example:

# Local directory
scaffolder new ./examples/basic-cli

# Remote Git repository
scaffolder new https://github.com/dajooo/scaffold-templates.git

# Remote Git repository + Subdirectory (use //)
scaffolder new https://github.com/dajooo/scaffold-templates.git//basic-cli

# Remote Git repository + Branch/Tag (use #)
scaffolder new https://github.com/dajooo/scaffold-templates.git#v2

# Short Syntax (degit-style)
scaffolder new user/repo                  # Defaults to https://github.com/user/repo
scaffolder new user/repo//subdir          # With subdirectory
scaffolder new user/repo#v1.0.0           # With tag/branch
scaffolder new user/repo//subdir#beta     # Subdir + Branch
scaffolder new github:user/repo           # Explicit GitHub
scaffolder new gitlab:user/repo           # GitLab
scaffolder new bitbucket:user/repo        # Bitbucket
scaffolder new codeberg:user/repo         # Codeberg

> **Note**: Scaffolder looks for a local directory first. If `./user/repo` exists, it uses it. If not, it clones from GitHub.

Creating Templates

A template is simply a directory containing:

1. A scaffold.yaml (or scaffolder.yaml) configuration file.
2. Any number of files and directories that will be copied to the target directory.

All files in the template directory (excluding scaffold.yaml and .git) are processed as Go templates, allowing you to inject variables directly into your code, configuration, and documentation.

Configuration (scaffold.yaml)

The scaffold.yaml file defines the project metadata, input variables, and post-generation steps.

name: My Template
target: "{{ .projectPath }}" # Where to create the project (default)

variables:
  # ... list of variables to ask the user ...

steps:
  # ... list of actions to run after copying files ...

---

Variables

Variables allow you to collect input from the user. These variables are then available in your file templates (e.g., {{ .variableName }}).

Common Attributes:

• name: The key used to reference the variable (e.g., projectName). If omitted for reusable kinds, a default is used.
• kind: The type of input (see below).
• prompt: The question to ask the user.
• default: Default value (string or list). Supports templating.
• if: Conditional expression (Go template that evaluates to true/false).

Standard Kinds

Kind	Description
input	Standard text input.
secret	Masked text input (for tokens/passwords).
confirm	Yes/No toggle. Returns "true" or "false".
select	Choose one option from a list.
multiselect	Toggle multiple options from a list. Returns comma-separated string.
autocomplete	Text input with filtered suggestions from options.

Example:

variables:
  - name: featureFlags
    kind: multiselect
    prompt: Enable optional features
    options: ["logging", "tracing", "metrics"]

Reusable "Magic" Kinds

These kinds come with smart defaults for name, prompt, and options/default logic, making your config minimal. You can override any attribute if needed.

Kind	Default Name	Behavior
project-name	projectName	Input. Defaults to the target directory name.
project-path	projectPath	Internal. The resolved output path.
go-module	goModule	Input. Defaults to github.com/your-org/{{ .projectName }}.
go-version	goVersion	Autocomplete. Populated with your installed Go version + previous minors.
git-init	initGit	Confirm. Defaults to true.
license	license	Select. Options: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, Unlicense.
package-manager	packageManager	Select. Options: pnpm, npm, yarn, bun.

Minimal Config Example:

variables:
  - kind: project-name
  - kind: go-module
  - kind: go-version
  - kind: license
  - kind: git-init

---

Steps

Steps define actions to take after the template files have been copied and rendered.

Common Attributes:

• kind: The type of step.
• if: Conditional expression.
• before: Message to print before execution.
• success: Message to print after successful execution.
• silent: If true, suppress command output (stdout/stderr).

Kinds

Kind	Description	Attributes
print	Print a message.	message (required)
command	Run a shell command.	command (required)
git-init	Initialize a git repo.	N/A
go-tidy	Run go mod tidy.	N/A
node-install	Install node deps.	Uses {{ .packageManager }} variable.

Example:

steps:
  - kind: go-tidy
  - kind: git-init
    if: '{{ eq .initGit "true" }}'
  - kind: print
    message: "Project created!"

---

Templating

Scaffolder uses standard Go text/template syntax.

Available Functions:

• contains: Checks if string contains substring. usage: {{ contains .list "item" }}
• hasPrefix: {{ hasPrefix .str "prefix" }}
• hasSuffix: {{ hasSuffix .str "suffix" }}
• upper: Uppercase.
• lower: Lowercase.
• replace: {{ replace .str "old" "new" }}
• split: Split string into slice.

Conditional Blocks:

{{ if eq .initGit "true" }}
# Git is enabled
{{ end }}