---
title: Scaffolding templates
---

# Writting a scaffolding template

typespec provides scaffolding functionality via the `tsp init` command.

```bash
tsp init <templateUrl>
```

## Specifying a minimum typespec version

If your template needs a functionality that was only added in a newer version of TypeSpec you might want to specify that in the template. This will warn the user that the template might not work as expected and prompt them to confirm that they want to continue.

To do so you can set `compilerVersion` in the each template configuration. The value is the minimum semver version required.

```json
{
  "compilerVersion": "0.51.0"
}
```

## Basic

A scaffolding template is a `json` document that can be hosted locally or online.
The root of the document is a dictionary allowing multiple templates to be hosted at the same location.

Each template needs at the minimum:

- key: Key of the template
- title: Human readable name of the template
- description: Extended description of the template.

Example:

```json
{
  "templateKey1": {
    "title": "Template #1",
    "description": "Create a project representing #1"
  },
  "templateKey2": {
    "title": "Template #2",
    "description": "Create a project representing #2"
  }
}
```

## Adding libraries

You can add a list of typespec libraries to include. This will automatically add those libraries to the `package.json` and imported in `main.tsp`.

```json
{
  "rest": {
    "title": "Rest API",
    "description": "Create a new project representing a REST API",
    "libraries": ["@typespec/rest", "@typespec/openapi3"]
  }
}
```

## Adding new files

Additional files.typespec or other types) can be generated by the initializer. The template takes a list of the files to copy and interpolate values.
Each file need the following properties:

- `path`: Absolute or relative path(to the template file) to the file
- `destination`: Relative path of the file relative to the project root.

```json
{
  "rest": {
    "title": "Rest API",
    "description": "Create a new project representing a REST API",
    "files": [{ "path": "./models.tsp", "destination": "./models.tsp" }]
  }
}
```

In models.tsp

```typespec
model {{parameters.ModelName}} {

}
```

### Interpolating values

The template can interpolate values in the files. The values available are anything available in the template configuration referenced as it is.
Examples:

- Reference a parameter `{{parameters.ModelName}}`
- Reference a the template title `{{title}}`

Additionally the following values and functions are available:

| Name                                  | Description                                                     |
| ------------------------------------- | --------------------------------------------------------------- |
| `directory`                           | Directory full path where the project should be initialized.    |
| `folderName`                          | Folder name where the project should be initialized.            |
| `name`                                | Name of the project.                                            |
| `libraries`                           | List of libraries to include                                    |
| `templateUri`                         | Path where this template was loaded from.                       |
| Functions                             |                                                                 |
| `toLowerCase(value: string)`          | Convert string to lower case                                    |
| `normalizePackageName(value: string)` | Normalize package name. It replaces `.` with`-` and toLowerCase |
| `casing.pascalCase(value: string)`    | Convert string to PascalCase                                    |
| `casing.camelCase(value: string)`     | Convert string to camelCase                                     |
| `casing.kebabCase(value: string)`     | Convert string to kebab-case                                    |

## Demanding additional input from the user

When generating files there might be a need for additional inputs to be retrieved from the user. For example the model name.
The template takes in a map of inputs that will get prompted to the user during initialization.

```json
{
  "rest": {
    "title": "Rest API",
    "description": "Create a new project representing a REST API",
    "inputs": {
      "modelName": {
        "type": "text",
        "description": "Name of the first model"
      }
    }
  }
}
```

Types of input supported:

- `text`: Ask for a raw text value.
