writing-scaffolding-template.md

title
Scaffolding templates

Writting a scaffolding template

typespec provides scaffolding functionality via the tsp init command.

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:

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

}

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.