writing-scaffolding-template.md

title
Scaffolding templates

Writting a scaffolding template

typespec provides scaffolding functionality via the tsp init command.

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.

{
  "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:

{
  "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.

{
  "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.

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

In models.tsp

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.

{
  "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.