Publish a template

Requirements

• A spin.toml file at the repository root.
• A _base/ directory containing at least one file.
• The template must render successfully using its default parameter values.

Authoring tips

Param prompts. Write prompts as questions the user can answer without reading the template source. Bad: name. Good: What is your project name?.

Script naming. Files in _pre/ and _post/ run sorted alphabetically after [[pre]]/[[post]] inline steps. Prefix with numbers to control order: 01-setup.sh, 02-init.sh.

Permissions. Files keep their mode from _base/. Executable files stay executable. Set the permission bits before publishing.

Test every param combination. Run spin new --dry-run and --print-params with each --param variant to verify the template renders correctly before publishing.

Versioning

Use Git branches or tags to version your template.

By default, spin new and spin add shallow-clone the repository's default branch. If you want users to pin a specific version, publish stable branches or tags and reference them in the repository URL.

README conventions

A template README should include:

• A short description.
• A usage example.
• The parameters users will be prompted for.

Example:

# go-cli-template

A minimal Go CLI starter for Spin.

## Usage

spin new myapp https://github.com/example/go-cli-template.git

## Parameters

- project_name (default: myproject)
- license (MIT, Apache-2.0, BSD-3-Clause, Proprietary)

Testing a template locally

spin new test-output --template ./my-template --dry-run
spin new test-output --template ./my-template --param project_name=test

Distribution options

Git repository

spin new myapp --template https://github.com/user/repo.git

Local path

spin new myapp --template ~/templates/my-template

Registry

Publish the template in a Spin registry so users can discover it with:

spin search
spin add <registry>/<template>