Installation

TypeSpec can be used in two ways:

• A standalone executable without any additional dependencies. Preview
• Npm package for use with Node.js and other package managers.

Standalone Preview

macOS and Linux

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

Windows

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

With Node.js

Install Node.js LTS and ensure you can run the npm command in a command prompt:

npm --version

Package manager

TypeSpec uses node package linking to manage dependencies. Any package manager that produce a node_modules directory should work:

• npm 7+. To update npm, run npm install -g npm
• pnpm
• yarn

Caution

Yarn will not automatically install implicit peerDependencies. TypeSpec libraries rely on this. Watch for warnings for any missing dependencies.

Install tsp

The first step is to install tsp, the TypeSpec compiler/CLI.

npm install -g @typespec/compiler

Install the VS and VSCode extensions

TypeSpec provides extensions for the following editors:

• Visual Studio Code
• Visual Studio

Create a new TypeSpec project

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 .

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.