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:

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

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 value	Version value	Result
`"PetStore"`	`"v1"`	`PetStore/output.v1.json`
`"PetStore"`	`undefined`	`PetStore/output.json`

Built-in variables

Variable name	Scope	Description
`cwd`	*	Points to the current working directory
`project-root`	*	Points to the the tspconfig.yaml file containing folder.
`output-dir`	emitter options	Common `output-dir` See output-dir
`emitter-name`	emitter options	Name of the emitter
`service-name`	service name	Name of the service
`service-name-if-multiple`	service name if multiple	Name of the service if multiple, undefined if one

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:

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

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:

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.

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

Emitter options support a nested structure, enabling complex configurations.

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

Config	Cli	Description
`output-dir`	`--output-dir`	Default output directory
`config`	`--config`	Path to config file or folder to search for config file.
`trace`	`--trace`	Specify tracing area to enable
`warn-as-error`	`--warn-as-error`	Treat warning as error
`imports`	`--import`	Additional imports to include
`emit`	`--emit`	Emitter configuration
`options`	`--option` or `--options`	Emitter configuration
`linter`		Linter configuration

`output-dir` - Configure the default output dir

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

output-dir: {cwd}/typespec-build

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

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

# Trace all.
trace: *

# or specific areas
trace:
  - import-resolution
  - projection

Trace can be provided using the --trace cli flag

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.

warn-as-error: true

or via the cli

tsp compile . --warn-as-error

`--ignore-deprecated`

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

tsp compile . --ignore-deprecated

`imports` - Configure additional imports

imports:
  - sidecar.tsp

Specify additional TypeSpec files to import

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.

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

or via the cli

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.

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>

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.

tsp compile . --no-emit

Other Command line flags

`--config`

Specify a different config file

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

`--watch`

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

tsp compile . --watch

`--nostdlib`

Don’t load the TypeSpec standard library.

tsp compile . --nostdlib

`--version`

Log the version of the tsp compiler.

tsp compile . --version

`--pretty`

Default: true

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

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:

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

--option "@typespec/openapi3.emitter-output-dir={project-root}/openapispec"

Directory{project-root}
- Directoryopenapispec
  - … openapi3 files …
- Directorytsp-output
  - Directory@typespec
    Directoryjsonschema
    … json schema files …

Configuration

Configuration file

Discovery

Schema

Extending Project Files

Variable interpolation

Interpolation of Emitter Path Config

Built-in variables

Project Parameters

Environment variables

Emitter Options

TypeSpec Configuration Options

output-dir - Configure the default output dir

trace - Configure what to trace

warn-as-error - Treating Warnings as Errors

--ignore-deprecated

imports - Configure additional imports

emit - Specifying which emitters to run

options - Configuring emitters