# TypeScript-website: the Gatsby site behind typescriptlang.org

> The repository that builds the TypeScript documentation site, its Playground and the tsconfig reference, organised as a pnpm workspace with a default branch called v2.

**microsoft/TypeScript-Website** — The Website and web infrastructure for learning TypeScript

- Repository: https://github.com/microsoft/TypeScript-Website
- Website: https://www.typescriptlang.org
- Stars: 2,554 · Forks: 1,527
- Language: TypeScript
- License: CC-BY-4.0
- Published: 2026-10-08 · Updated: 2026-10-08 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoft-typescript-website

## Cloning and running the site on port 8000

The README's getting started section names the prerequisites directly: pnpm workspaces, Node 20 or newer, and watchman, with a chocolatey package offered for Windows users. `package.json` narrows that requirement further, declaring an engine of Node 20.19 or above. With those installed, the documented sequence is:

```sh
cd TypeScript-website
pnpm install
code .

# Then:
pnpm bootstrap
# Optional, grab the translations:
pnpm docs-sync pull microsoft/TypeScript-Website-localizations#main 1

# Now you can start up the website
pnpm start
```

Two details in that block matter. The translations pull is optional and points at a separate repository, `microsoft/TypeScript-Website-Localizations`, which is how translated pages get into the build without living here. And `pnpm bootstrap` is a distinct step from `pnpm install`, which is the first hint that this workspace has a build phase beyond dependency resolution.

`pnpm start` runs the site on port 8000 and creates a builder worker for every package, so a change outside the site content still triggers a compile and a lint. That is the mechanism that makes the monorepo feel like one thing rather than eleven.

## The default branch is v2 and pushes to it deploy to production

The deployment section is one sentence: pushes to the branch `v2` deploy to production, and the build logs are in GitHub Actions. The repository's default branch is indeed `v2`, which is unusual for a Microsoft project and worth internalising before you branch.

The consequence for a contributor is concrete. There is no staging step described, and the branch that serves typescriptlang.org is the branch you branch from. A pull request therefore targets the live branch, which means review discipline matters more here than in a repository with a separate mainline and release branch. Anyone expecting the usual main/develop/release layout will get it wrong on the first push.

The troubleshooting guide lives at `docs/Setup Troubleshooting.md`, and the README points there for setup problems rather than spreading the answers across the page. An hour-long video walkthrough of the codebase, deployment and tooling is also linked for readers who want the whole shape at once.

## Four packages that other projects actually consume

Much of this repository is site infrastructure, but four packages are published to npm and carry their own version numbers. The recent releases on the repository are all of them: `@typescript/vfs` at 1.6.5, `@typescript/twoslash` at 3.2.13, and `@typescript/sandbox` at 0.1.15, all published on 2026-09-22.

`@typescript/twoslash` is a markup extension for code samples. It compiles a snippet so that the documentation can show real inferred types and real errors next to the example, rather than a hand-written approximation that goes stale. `@typescript/vfs` runs TypeScript projects entirely in memory in a browser or Node environment, which is what lets the Playground and any sandboxed documentation execute code without a server. `@typescript/sandbox` provides the editor aspect of the Playground REPL for any site that wants a Monaco editor with TypeScript or JavaScript. The fourth, create-playground-plugin, is a template: `npm init playground-plugin [name]` scaffolds one.

So the repository is two projects at once. The website is the visible half; the npm packages are the reusable half, and their release cadence is what the version numbers in the release list are tracking.

## Two licences in one repository, and changesets guard the packages

The tree contains both `LICENSE` and `LICENSE-CODE`. The README's legal notice grants Microsoft and contributors a licence over the documentation and other content under Creative Commons Attribution 4.0, which is the standard choice for documentation meant to be reused with attribution. The separate code licence applies to the code, which is consistent with how npm packages published from this monorepo need to be licensed to be installable.

If you copy handbook text into your own project, the CC-BY terms travel with it and you owe attribution. If you depend on `@typescript/vfs` you are in the code half. Those are different obligations and the repository keeps them in separate files rather than blurring them into one grant.

Release discipline is enforced by changesets. `pnpm changeset` walks you through picking the affected packages, files are written into `.changeset/`, and CI fails if a pull request modifies a public package without one. Website-only changes need no changeset, and a change to a published package that does not affect published code can use `pnpm changeset --empty`. The root `package.json` also pins TypeScript 6.0.2 through pnpm overrides and applies a patch to `gatsby-remark-shiki-twoslash`, which is the sort of detail that tells you this build is pinned deliberately.

## Regenerating the tsconfig reference from the compiler

The tsconfig-reference package is the part of this repository with a genuinely mechanical job: it generates the API reference for tsconfig.json from the compiler itself, rather than from prose someone maintains by hand. The pipeline has distinct steps, and the README is careful to keep them separate:

```sh
# Generate JSON from the typescript cli
pnpm run --filter=tsconfig-reference generate-json
# Jams them all into a single file
pnpm run --filter=tsconfig-reference generate-markdown
```

Validation is separate again, with `pnpm run --filter=tsconfig-reference test` to run the docs tests, `lint` to run the linter without a build, and `lint resolveJson` to target a single document. The schema is produced by `pnpm run --filter=tsconfig-reference build` and lands at `packages/tsconfig-reference/scripts/schema/result/schema.json`.

Because the source of truth is the compiler, the documentation cannot drift from the flags the compiler actually accepts, which is a better guarantee than any review process. The cost is that the reference is only as current as the TypeScript version pinned in the workspace, and the README links a guide on updating the TypeScript version for exactly that step.

## What a contributor is agreeing to

The contributing section states that most contributions require agreeing to a Contributor License Agreement declaring that you have the right to grant, and do grant, the rights to your contribution. A bot checks whether you need to sign and decorates the pull request accordingly, and you only do it once across the Microsoft CLA family.

That is a different contributor experience from a repository under a plain MIT or Apache grant, and it is worth knowing before writing a patch rather than after. The repository also adopts the Microsoft Open Source Code of Conduct, with a published FAQ and a contact address.

The practical boundary for a reader deciding whether this repository is relevant: if you are learning TypeScript, typescriptlang.org is the place to read, and this repository is how that site is built. If you want to contribute documentation, the handbook pages live here, the community meta package generates contribution metadata about who edited which page, and a CLA is part of the deal. If you want the compiler, this is the wrong repository.

## Conclusion

This repository matters to you if you maintain TypeScript documentation, build the Playground inside your own site, or need the tsconfig reference regenerated against a new compiler release. It is not the TypeScript compiler and it is not a starter template; the cost of entry is watchman, pnpm workspaces and a Gatsby build with patches applied. Two things to verify before you start: pushes go to the `v2` branch and deploy to production, so work belongs on a branch off `v2` rather than a mainline assumption, and the code under `packages/` is published to npm under its own licence while the site content is CC-BY-4.0, which matters if you copy documentation text into your own project.

## FAQ

### How do I run the TypeScript website locally?

You need pnpm workspaces, Node 20 or newer and watchman. Clone the repository, run `pnpm install`, then `pnpm bootstrap`, and `pnpm start` serves the site on port 8000. The README notes that Node 20.19 or above is required.

### Which branch does a pull request need to target?

Work from the `v2` branch, which is the repository's default branch. The README states that pushes to `v2` deploy to production, so there is no separate release branch to target.

### What do the npm packages published from this repository do?

`@typescript/twoslash` is a code sample markup extension that compiles snippets to show real types and errors. `@typescript/vfs` runs TypeScript projects in memory in a browser or Node environment, and `@typescript/sandbox` provides the Monaco editor surface used by the Playground.

### What licence applies to the TypeScript website content?

Documentation and other content in the repository are granted under Creative Commons Attribution 4.0, and the tree carries a separate `LICENSE-CODE` file for the code. Reusing handbook text therefore carries an attribution obligation that does not apply to the packages.

## Sources

- [License: CC-BY-4.0](https://github.com/microsoft/TypeScript-Website/blob/v2/LICENSE)
- [microsoft/TypeScript-Website on GitHub](https://github.com/microsoft/TypeScript-Website)
- [Project website](https://www.typescriptlang.org)
- [README](https://github.com/microsoft/TypeScript-Website/blob/v2/README.md)
- [Releases](https://github.com/microsoft/TypeScript-Website/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-typescript-website