---
title: Scaffolding templates
---

# Writting a scaffolding template

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

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

## 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 |

## 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.
