Installation

Install TypeSpec

TypeSpec can be used in two ways:

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

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 (optional)

To have access to the tsp command globally, install the @typespec/compiler package: Altnatively, you can run npx tsp instead in any project that has the compiler as a dependency.

npm install -g @typespec/compiler

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