Skip to content

Configuration

The TypeSpec compiler and libraries can be configured either via a configuration file or command line flags.

Configuration file

TypeSpec configuration can be provided via the tspconfig.yaml configuration file.

Discovery

The TypeSpec compiler will look for the closest tspconfig.yaml file located in the same directory or closest parent directory from the TypeSpec entrypoint.

For example if running tsp compile /dev/foo/bar/main.tsp, the compiler will lookup the file at the folllowing paths (in order):

  • /dev/foo/bar/tspconfig.yaml
  • /dev/foo/tspconfig.yaml
  • /dev/tspconfig.yaml
  • /tspconfig.yaml

Schema

The file is a yaml document with the following structure. See the next section for details on each option.

model TypeSpecProjectSchema {
extends?: string;
parameters?: Record<{default: string}>
"environment-variables"?: Record<{default: string}>
"warn-as-error"?: boolean;
"output-dir"?: string;
"trace"?: string | string[];
imports?: string;
emit?: string[];
options?: Record<unknown>;
linter?: LinterConfig;
}
model LinterConfig {
extends?: RuleRef[];
enable?: Record<RuleRef, boolean>;
disable?: Record<RuleRef, string>;
}

Extending Project Files

There may be instances where you want to build different folders with varying options (such as different emitters), but still want to share some common configurations.

In such cases, you can use the extends property in the configuration file.

For instance, in <my-pkg>/tspconfig.yaml:

tspconfig.yaml
options:
emitter1:
some-option: my-name
emitter2:
some-other-option: This is a title

in <my-pkg>/proj2/tspconfig.yaml, enable emitter1 using the options specified in the parent tspconfig.yaml

proj2/tspconfig.yaml
extends: ../tspconfig.yaml
emit:
- emitter1

Variable interpolation

The TypeSpec project file provides variable interpolation using:

  • built-in variables
  • environment variables
  • config file parameters
  • emitter options can reference each other

Variable interpolation is done using an variable expression surrounded by { and }. ({<expression>})

Examples:

  • {output-dir}/my-path
  • {env.SHARED_PATH}/my-path

Interpolation of Emitter Path Config

Certain emitter configurations can be interpolated using a specific rule designed to collapse a path.

If a variable is succeeded by a / or . and the emitter responsible for interpolating the config doesn’t supply that variable, the path segment will be omitted.

For instance, consider the following config value: {service-name}/output.{version}.json Here’s what would be produced:

Service name valueVersion valueResult
"PetStore""v1"PetStore/output.v1.json
"PetStore"undefinedPetStore/output.json
undefined"v1"output.v1.json
undefinedundefinedoutput.json

Built-in variables

Variable nameScopeDescription
cwd*Points to the current working directory
project-root*Points to the the tspconfig.yaml file containing folder.
output-diremitter optionsCommon output-dir See output-dir
emitter-nameemitter optionsName of the emitter

Project Parameters

A TypeSpec project file can define certain parameters that can subsequently be specified through the CLI. Parameters can be organized in a nested structure, to access different levels of the structure, use dots (.) in the variable expression. Therefore, parameter names should not contain . in their name.

The {cwd} and {project-root} variables can be utilized in the default value of these parameters.

These parameters can then be referred to by their name in a variable interpolation expression.

All parameters must have a default value. Example:

tspconfig.yaml
parameters:
base-dir:
default: "{cwd}"
output-dir: {base-dir}/output

The parameter can then be specified via --arg in this format --arg "<parameter-name>=<value>" and for nested structures --arg "<parameter-name>.<nested-parameter-name>=<value>"

Terminal window
tsp compile . --arg "base-dir=/path/to/base"

Environment variables

A TypeSpec project file can specify which environment variables it can interpolate.

The {cwd} and {project-root} variables can be used in the default value of these environment variables.

These environment variables can then be referred to by their name in a variable interpolation expression, using the env. prefix.

All environment variables must have a default value.

Example:

tspconfig.yaml
environment-variables:
BASE_DIR:
default: "{cwd}"
output-dir: {env.BASE_DIR}/output

Emitter Options

Emitter options can refer to each other by using the other option’s name as the variable expression.

Interpolation is only possible among emitter options from the same emitter.

tspconfig.yaml
options:
@typespec/openapi3:
emitter-output-dir: {output-dir}/{emitter-sub-folder}
emitter-sub-folder: bar

Emitter options support a nested structure, enabling complex configurations.

tspconfig.yaml
options:
emitter-sub-folder:
sub-folder: bar

To set these values via the CLI, use dots to navigate deeper levels in the definition. --option "<option-name>.<nested-option-name>=<value>" Due to this capability, emitter option names should not contain a . in their name.

TypeSpec Configuration Options

ConfigCliDescription
output-dir--output-dirDefault output directory
config--configPath to config file or folder to search for config file.
trace--traceSpecify tracing area to enable
warn-as-error--warn-as-errorTreat warning as error
imports--importAdditional imports to include
emit--emitEmitter configuration
options--option or --optionsEmitter configuration
linterLinter configuration

output-dir - Configure the default output dir

Specify the common output-dir for all emitters. See this to configure per emitter.

tspconfig.yaml
output-dir: {cwd}/typespec-build

Output dir can be provided using the --output-dir cli flag

Terminal window
tsp compile . --output-dir "./typespec-build"

Output dir must be an absolute path in the config. Use {cwd} or {project-root} to explicitly specify what it should be relative to.

See output directory configuration for mode details

trace - Configure what to trace

Configure what area to trace. See tracing docs

tspconfig.yaml
# Trace all.
trace: *
# or specific areas
trace:
- import-resolution
- projection

Trace can be provided using the --trace cli flag

Terminal window
tsp compile . --trace import-resolution --trace projection

warn-as-error - Treating Warnings as Errors

All warnings will be treated and emitted as errors, resulting in a non-zero exit code in the event of a warning.

It is recommended to use this feature in Continuous Integration (CI) to ensure all warnings are addressed.

tspconfig.yaml
warn-as-error: true

or via the cli

Terminal window
tsp compile . --warn-as-error

--ignore-deprecated

Suppress all deprecated diagnostics that are raised when declarations are marked with the #deprecated directive.

Terminal window
tsp compile . --ignore-deprecated

imports - Configure additional imports

tspconfig.yaml
imports:
- sidecar.tsp

Specify additional TypeSpec files to import

Terminal window
tsp compile . --import "sidecar.tsp"

emit - Specifying which emitters to run

Specify which emitters to use and their options if applicable.

The value can be the name of an emitter or a path to the emitter package/entrypoint.

tspconfig.yaml
emit:
- emitter1 # Package name
- /path/to/emitter2 # Give a path to an emitter

or via the cli

Terminal window
tsp compile . --emit emitter1 --emit /path/to/emitter2

options - Configuring emitters

Emitters can define a set of options, those can be set as the value of the map.

tspconfig.yaml
options:
# Enable and configure emitter1
emitter1:
option1: "option1-value"
option2: "option1-value"
# Only enable emitter2
emitter2: true

Emitters options can also be provided using the --option in this format --option=<emitterName>.<optionName>=<value>

Terminal window
tsp compile . --option "emitter1.option1=option1-value"

Options specified via the CLI take precedence over the ones specified in tspconfig.yaml.

Emitters built-in options

emitter-output-dir

Represent the path where the emitter should be outputing the generated files.

Default: {output-dir}/{emitter-name}

See output directory configuration for mode details

linter - Setting Up Linters

This allows you to configure the linter rules to be enabled in this repository. When referencing a rule or ruleset, use their ID, which follows the format <libraryName>:<ruleName>.

linter:
extends: # Extend `recommended` ruleset from @typespec/best-practices library
- "@typespec/best-practices/recommended"
enable: # Explicitly enable some rules
"@typespec/best-practices/no-x": true
disable: # Disable some rules defined in one of the ruleset extended.
"@typespec/best-practices/no-y": "This rule cannot be applied in this project because X"

CLI Flags for Emitter Control

--no-emit

This flag disables emitting. If emitters are still specified, the emitter will run but it should not write anything to the disk.

This flag can also be used to suppress the “There are no emitters” warning.

tspconfig.yaml
tsp compile . --no-emit

Other Command line flags

--config

Specify a different config file

Terminal window
tsp compile . --config ./tspconfig.alt.yaml

--watch

Start the tsp compiler in watch mode: watch for file changes and compile on save.

Terminal window
tsp compile . --watch

--nostdlib

Don’t load the TypeSpec standard library.

Terminal window
tsp compile . --nostdlib

--version

Log the version of the tsp compiler.

Terminal window
tsp compile . --version

--pretty

Default: true

Enable/Disable pretty logging (colors, diagnostic preview, etc.).

Terminal window
tsp compile . --pretty=false

Configuring Output Directory

The TypeSpec compiler assigns a unique output directory to each emitter that runs, in order to minimize conflicts. By default, the output directory of an emitter is set to:

{output-dir}/{emitter-name}

where:

  • output-dir is the common output directory for the compiler, which can be configured via --output-dir.
  • emitter-name is the name of the emitter package (for example, /openapi3).

For instance, if the emitters @typespec/openapi3 and @typespec/jsonschema are given, the default output folder structure would be:

  • Directory{project-root}/tsp-output
    • Directory@typespec:
      • Directoryopenapi3
        • openapi3 files …
      • Directoryjsonschema
        • json schema files …

You can change the compiler’s output-dir with --output-dir or by setting that value in the tspconfig.yaml, which would result in the following structure:

Terminal window
--output-dir={cwd}/my-custom-output-dir
  • Directory{cwd}/my-custom-output-dir
    • Directory@typespec:
      • Directoryopenapi3
        • openapi3 files …
      • Directoryjsonschema
        • json schema files …

To change a specific emitter’s output directory, you can set the emitter-output-dir option for that emitter:

Terminal window
--option "@typespec/openapi3.output-dir={project-root}/openapispec"
  • Directory{project-root}
    • Directoryopenapispec
      • openapi3 files …
    • Directorytsp-output
      • Directory@typespec
        • Directoryjsonschema
          • json schema files …