Creating Spin templates

Authoring the Content
- Expression Syntax
Authoring the Manifest
Supporting spin add
Hosting Templates in Git

Spin templates allow a Spin developer to quickly create the skeleton of an application or component, ready for the application logic to be filled in.

A template consists of two directories, content and metadata.

The content directory contains all the files you’d like to be copied into the Spin application directory, such as source code, the spin.toml file, standard assets, precompiled modules, etc. These files can contain placeholders so the user of the template can customize the end result.
The metadata directory contains the files that control how the template is instantiated. In this version of Spin, the only file in this directory should be the template manifest.

For examples of the directory contents, see the templates directory in the Spin GitHub repository.

Templates must always be shared in a templates directory. This allows the installer to locate them in repos that contain other content.

Authoring the Content

Copy all the files that you want to be copied as part of the template into the content directory. If you do nothing more, they will be copied verbatim. Often, though, you’ll want to allow the user to put their own values in - for example, a project name, or an HTTP route.

To do this, replace the text you want the user to be able to substitute with an expression of the form {{parameter-name}}, where parameter-name is an identifier of your choice. You will need to add an entry to the manifest matching this name - see below.

You can reuse a parameter in more than one place - it will be prompted only once and will get the same value in each place.

You can also transform the user value by specifying a filter after a bar: {{parameter-name | filter-name}}. This is particularly useful when you want to conform to specific language conventions. The following filters are supported:

Name	Effect
`kebab_case`	Transforms input into kebab case, e.g. `My Application` to `my-application`
`snake_case`	Transforms input into snake case, e.g. `My Application` to `my_application`
`pascal_case`	Transforms input into Pascal case, e.g. `my application` to `MyApplication`

Expression Syntax

Content uses the Liquid template language. See the Liquid documentation for the available syntax and control tags.

A common pitfall occurs because some entries in spin.toml, such as component variable templates, use the same double-brace syntax as Liquid does. If you want to generate a line such as my-secret = "{{ secret }}", you must escape the double braces, for example using the Liquid raw tag. If you don’t do this, Liquid will look for a template parameter called secret instead!

Authoring the Manifest

The template manifest is a TOML file. It must be named spin-template.toml:

manifest_version = "1"
id = "my-application"
description = "An application"
tags = ["my-tag"]

[parameters]
# Example parameter
project-name = { type = "string", prompt = "Project name" }

manifest_version specifies the format this manifest follows. It must be "1".
id is however you want users to refer to your template in spin new. It may contain letters, digits, hypens and underscores.
description is optional. It is shown when displaying the template.
tags is optional. These are used to enable discoverability via the Spin CLI. For example, spin new --tag my-tag will prompt selection for a template containing "my-tag".

The parameters table is where you list the placeholders that you edited into your content for the user to substitute. You should include an entry for each parameter. The key is the parameter name, and the value a JSON document that contains at minimum a type and prompt. type must currently be string. prompt is displayed when prompting the user for the value to substitute.

The document may also have a default, which will be displayed to the user and can be accepted by pressing Enter. It may also specify constraints on what the user is allowed to enter. The following constraints are supported:

Key	Value and usage
`pattern`	A regular expression. The user input must match the regular expression to be accepted.

Supporting `spin add`

The spin add command lets users add your template as a new component in an existing application. If you’d like to support this, you’ll need to add a few items to your metadata.

In the metadata directory, create a folder named snippets. In that folder, create a file containing the (templated) manifest just for the component to be added.
- Don’t include any application-level entries, just the component section.
- If your template contains component files, remember they will be copied into a subdirectory, and make sure any paths reflect that.
In the spin-template.toml file, add a table called add_component, with the following entries:

Key	Value and usage
`snippets`	A subtable with an entry named `component`, whose value is the name of the file containing the component manifest template. (Don’t include the `snippets` directory prefix - Spin knows to look in the `snippets` directory.)
`skip_files`	Optional array of content files that should not be copied when running in “add component” mode. For example, if your template contains a `spin.toml` file, you should use this setting to exclude that, because you want to add a new entry to the existing file, not overwrite it.
`skip_parameters`	Optional array of parameters that Spin should not prompt for when running in “add component” mode.

Here is an example add_component table from a HTTP template:

[add_component]
skip_files = ["spin.toml"]
skip_parameters = ["shared-prefix"]
[add_component.snippets]
component = "component.txt"

For examples from the Spin project, see http-rust and static-fileserver.

Hosting Templates in Git

You can publish templates in a Git repo. The templates must be in the /templates directory, with a subdirectory per template.

When a user installs templates from your repo, by default Spin looks for a tag to identify a compatible version of the templates. This tag is of the form spin/templates/vX.Y, where X is the major version, and Y the minor version, of the user’s copy of Spin. For example, if the user is on Spin 0.3.1, templates will be installed from spin/templates/v0.3. If this tag does not exist, Spin installs templates from HEAD.