---
id: installation
title: Installation
slug: docs
---

import { Aside, Badge, Tabs, TabItem, FileTree, Steps } from "@astrojs/starlight/components";

## Install TypeSpec

TypeSpec can be used in two ways:

- Npm package for use with [Node.js](https://nodejs.org/)
- A standalone executable without any additional dependencies. <Badge text="Experimental" variant="caution" />

<Tabs>
  <TabItem label="Node.JS">

<Steps>

1. Install [Node.js LTS](https://nodejs.org/en/download/)

2. Install the TypeSpec CLI

   ```bash
   npm install -g @typespec/compiler
   ```

</Steps>

[See package manager doc](../handbook/package-manager.md) for more information on package managers.

  </TabItem>
  <TabItem label="Standalone (Experimental)">

<Aside type="caution">The standalone CLI is currently experimental.</Aside>

To install, paste this into a terminal:

<Tabs>
  <TabItem label="macOS">
  
```bash
curl -fsSL https://typespec.io/install.sh | bash
```

  </TabItem>
  <TabItem label="Windows">

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

  </TabItem>
  <TabItem label="Linux">
  
```bash
curl -fsSL https://typespec.io/install.sh | bash
```

  </TabItem>
</Tabs>

  </TabItem>
</Tabs>

## Install the VS and VS Code extensions

TypeSpec provides extensions for the following editors:

- [Visual Studio Code](./editor/vscode.md)
- [Visual Studio](./editor/vs.md)

## Create a new TypeSpec project

<Tabs>
  <TabItem label="CLI">

<Steps>

1. Create a new TypeSpec project.

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

   ```bash
   tsp compile .
   ```

</Steps>
  </TabItem>
  <TabItem label="VS Code">

<Steps>

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.

</Steps>

![vscode_project_scaffolding.gif](https://raw.githubusercontent.com/microsoft/typespec/main/website/src/content/docs/docs/images/vscode_project_scaffolding.gif)

  </TabItem>
</Tabs>

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

{/* prettier-ignore */}
<FileTree>
- main.tsp
- tspconfig.yaml
- package.json
- node_modules/
- tsp-output/
  - @typespec/
    - openapi3/
      - openapi.yaml
</FileTree>

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