Installation

Install TypeSpec

TypeSpec can be used in two ways:

• Npm package for use with Node.js
• A standalone executable without any additional dependencies. Experimental

Node.JS

1. Install Node.js LTS

2. Install the TypeSpec CLI

   npm install -g @typespec/compiler

See package manager doc for more information on package managers.

Standalone (Experimental)

Caution

The standalone CLI is currently experimental.

To install, paste this into a terminal:

macOS

curl -fsSL https://typespec.io/install.sh | bash

Windows

powershell -c "irm typespec.io/install.ps1|iex"

Linux

curl -fsSL https://typespec.io/install.sh | bash

Install the VS and VS Code extensions

TypeSpec provides extensions for the following editors:

• Visual Studio Code
• Visual Studio

Create a new TypeSpec project

CLI

1. Create a new TypeSpec project.

   tsp init

   This will prompt you with a few questions. Pick the Generic REST API template, your project name, and make sure the @typespec/http and @typespec/openapi3 libraries are selected.

2. Run a build to generate the OpenAPI specification output file.

   tsp compile .

VS Code

1. Invoke the command >TypeSpec: Create TypeSpec Project to create TypeSpec project, or click Create TypeSpec Project button from the Primary Sidebar of Explorer.
2. Follow Quick Picks to select root folder of your project, pick the Generic REST API template, input your project name, make sure the @typespec/http and @typespec/openapi3 libraries are selected, then return to launch project scaffolding.

You should now have a basic TypeSpec project setup with a structure looking like this:

• main.tsp
• tspconfig.yaml
• package.json
• Directorynode_modules/

  • …
• Directorytsp-output/

  • Directory@typespec/

    • Directoryopenapi3/

      • openapi.yaml

• main.tsp: The entry point for your TypeSpec build. This file typically contains the main definitions for your models, services, and operations.
• tspconfig.yaml: Configuration file for the TypeSpec compiler, specifying options and settings for the build process.
• package.json: Contains metadata about the project, including dependencies, scripts, and other project-related information.
• node_modules/: Directory where npm installs the project’s dependencies.
• tsp-output/: Directory where the TypeSpec compiler outputs generated files.
• openapi.yaml: The generated OpenAPI specification file for your API, detailing the API’s endpoints, models, and operations. The output can vary based on the target format specified in the tspconfig.yaml file.

You can also run tsp compile . --watch to automatically compile changes on save.