
I maintain Zod, which is a schema library. Zod let's people declare an email schema like this:

```ts
import {z} from 'zod';

z.string().email();
```

A lot of people think every _technically valid_ email address should pass validation by that schema. I [used to think that](https://github.com/colinhacks/zod/issues/639#issuecomment-917223045) too.

Over the years I've merged several PRs to make the email regex more "technically correct". Most recently, I merged a PR that adds support for _IPv6 addresses_ as the domain part of an email. They look like this and I hate them:

```
jonny@[ipv6:7e95:0559:10f2:21e9:9dab:7309:c116:ca3b]
```

Turns out that PR also broke plain old subdomains: `user@subdomain.domain.com`. That means Zod currently fails to parse my _mom's current email address_ but Jonny up there can parse his freakish IPv6 email.

This caused a spiritual crisis and made me re-evaluate my whole stance on what `z.string().email()` should do. Zod's users are mostly engineers who are building apps. When you're building an app, you want to make sure your users are providing normal-ass email addresses. So that's what `z.string().email()` is going do.

So I rewrote the regex from scratch to be simple and reasonable. Here's what I came up with:

```ts
/^([A-Z0-9_+-]+\.?)*[A-Z0-9_+-]@([A-Z0-9][A-Z0-9-]*\.)+[A-Z]{2,}$/i;
```

Let's break that down in plain English:

**The username** (AKA "local part")

- can use these characters: `[a-zA-Z0-9-._]`
- can't have two dots in a row
- can't start or end with a dot

**The domain**

- can use these characters: `[a-zA-Z0-9-.]`
- must have one or more dots in it
- can't have two dots in a row
- can't start or end with a dot
- can't start or end with a hyphen
- must end with a "TLD" that's 2+ letters, only `[a-zA-Z]` allowed

It is _not_ trying to be [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322) compliant. It's not going to check if the TLD is real. And it's not going to implement any of this craziness:

- No "printable" characters: `wtf-!#$%&'*/=?^_{|}~@mail.com`
- No quoted local parts: `"zod is cool"@mail.com`
- No comments: `regexiscool(kinda)@mail.com`
- No IPv4: `billie@[1.2.3.4]`
- No IPv6: `jonny@[ipv6:7e95:0559:10f2:21e9:9dab:7309:c116:ca3b]`
- No emoji: `👎@mail.com`

But for reasonable people, it'll do.


An email regex for reasonable people


> EDIT: A previous version of this post recommended `publishConfig`, operating under the mistaken belief that it could be used to override `"exports"` during `npm publish`. As it turns out, `npm` only uses `"publishConfig"` to override certain `.npmrc` fields like `registry` and `tag`, whereas `pnpm` has expanded its use to override package metadata like `"main"`, `"types"`, and `"exports"`. There are a number of reasons you may not wish to strongly couple your deployment logic to `pnpm` (detailed in the `publishConfig` section below). My updated recommendation is to use a custom export condition plus `customConditions` in `tsconfig.json`.

> Jump into the code: https://github.com/colinhacks/live-typescript-monorepo

In development, your TypeScript code should feel "alive". When you update your code in one file, the effects of that change should propagate to all files that import it instantaneously, with no build step. This is true even for monorepos, where you may not be importing things from a file, but from a local package.

```diff
- import { Fish } from "../pkg-a/index";
+ import { Fish } from "pkg-a"
```

This is vital to TypeScript's value proposition.

This post explains a few strategies you can use to make your TypeScript monorepo feel more alive. Refer to the corresponding repo where you can play around with the code for each strategy: https://github.com/colinhacks/live-typescript-monorepo

The repo contains three subdirectories, each containing a monorepo with the following file structure:

```
.
├── package.json
├── packages
│   ├── pkg-a
│   │   ├── README.md
│   │   ├── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── pkg-b
│       ├── README.md
│       ├── index.ts
│       ├── package.json
│       └── tsconfig.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── tsconfig.base.json
└── tsconfig.json
```

This is a pnpm monorepo (`pnpm-workspace.yaml`) with two packages, `pkg-a` and `pkg-b`. **`pkg-b` has a dependency on `pkg-a`**. Each package has a `tsconfig.json` that extends a `tsconfig.base.json` in the root of the monorepo.

Here is a quick rundown of the solutions. Don't worry if there are terms you're not familiar with, everything is explained in the breakdown.

1. Use project references (`"references"` in `tsconfig.json`)
2. Use `publishConfig` in `package.json` to specify `.ts` file in development and `.js` file in production. _Requires `pnpm`._
3. Configure `compilerOptions.paths` in `tsconfig.json` to override resolution for local package names.
4. **Recommended** Define a custom conditional export condition in `package.json#exports`.

Note that I'm explaining all the solutions I found for the sake of education, but the recommended solution is #5 (custom export conditions) so feel free to jump ahead if you're just looking for a solution!

## A primer: runtime vs. static

The fundamental annoyance here is this: Node.js has an algorithm for _module resolution_. When it sees an import from a _bare specifier_ like `"pkg-a"`, it scans up the directory tree checking for a directory called `"pkg-a"` in each `node_modules` folder it encounters. Once it finds `"pkg-a"`, it reads the `package.json` inside and uses the `main` and `exports` to figure out how to resolve the bare specifier to a file on disk.

The TypeScript server does _almost_ the same thing, though it uses the `"types"` field (or the `"types"` export condition in `"exports"`) to find the _declaration file_ corresponding to a particular package. There are also _lots_ of ways to hack TypeScript's module resolution algorithm. (We'll get to that in a bit.)

But in development, we want things to behave differently. We want the TypeScript server to look at our "raw" `.ts` files when resolving imports to other local packages in our monorepo, _not_ the compiled declaration files. Similarly, when we execute our local code (say, when running tests) we want it to "run" our TypeScript source code. You shouldn't need to rebuild your project before running tests.

So we need a way to hijack module resolution both statically (for TypeScript) and at runtime (for Node.js or tools like Vitest). We also need to make sure _both_ of these things are hijacked in a way that they agree with each other. If TypeScript is looking at our `src/index.ts` files but Node.js is still importing `lib/index.js`, the types may not reflect the runtime behavior of the code. You may have seen this referred to as _static-runtime disagreement_.

Okay, enough background. Let's get into the details.

## 1. Project references

> The code for this is under the `project-references` subdirectory.
> Project references are a TypeScript feature that make it easier to split a large TypeScript codebase into chunks that are typechecked separately by the TypeScript server. This can be a huge performance win for large codebases.

In our monorepo, `pkg-b` has a dependency on `pkg-a`. So in our `packages/pkg-b/tsconfig.json`, we can add a reference to `pkg-a` like so:

```json
{
  "references": [{"path": "../pkg-a"}]
}
```

Unfortunately the `"references"` field is [not inherited](https://twitter.com/andhaveaniceday/status/1798613232208527826) when you use `"extends"`, so you have to declare it in every package's `tsconfig.json`. If your monorepo packages have a lot of interconnection, this can get unwieldy fast.

You may also notice that `"references"` will end up [mirroring the `"dependencies"`](https://twitter.com/andhaveaniceday/status/1798717319990112609) list in `package.json`. These will need to be kept in sync to work as expected. There are tools ([`nx`](https://nx.dev/)) that try to automate this, but the need to run a command to re-generate configs starts to feel like a "build step" in itself...and that's what we're trying to avoid.

> There are [long-gestating efforts](https://github.com/microsoft/TypeScript/issues/25376) to make this more ergonomic, but there seems to be little movement on this front.

The final nail in the coffin is the difficulty of incorporating `"references"` into runtime module resolution. It's purely a TypeScript feature, and no tools incorporate this into their module resolution. So in all likelihood, you'd need to use one of the approaches below _in conjunction_ with project references to achieve true "live types" with runtime `.ts` resolution.

> There are absolutely scenarios where project references are indispensable. If you have a large enough monorepo, project references may become necessary to avoid re-typechecking the entire codebase when you make a change! But for non-giant projects, they aren't necessary and introduce too much complexity and potential footguns.

## 2. `"publishConfig"` in `package.json`

> This approach requires `pnpm` to work! The `publishConfig` field behaves very differently between `npm publish` and `pnpm publish`.

One obvious solution is just to have each package's `package.json` point to our `.ts` files in `package.json`.

```json
{
  "name": "pkg-a",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": {
      "import": "./src/index.ts",
      "require": "./src/index.ts",
      "types": "./src/index.ts"
    },
    "./package.json": "./package.json"
  }
}
```

This introduces an obvious and immediate problem. We can't publish our raw `.ts` files to npm without breaking most tools. They need to be properly transpiled to JavaScript first. When we run `npm publish`, we need these fields to point to the appropriate `lib/index.js` and `lib/index.d.ts` files.

Many people have written custom build scripts that will duplicate `package.json` and rewrite these fields before publishing. Fortunately the good folks at `pnpm` have given us a better option: `publishConfig`.

```json
{
  "name": "pkg-a",

  // development config
  "exports": "./src/index.ts",

  // production config
  "publishConfig": {
    "main": "./lib/index.js",
    "types": "./lib/index.d.ts",
    "exports": {
      ".": {
        "import": "./lib/index.js",
        "require": "./lib/index.js",
        "types": "./lib/index.d.ts"
      },
      "./package.json": "./package.json"
    }
  }
}
```

When you run `pnpm publish`, pnpm will read the `publishConfig` field in `package.json` and use those values to override the top-level values for `"main"`, `"exports"`, and `"types"`.

> While `npm` supports a field called `publishConfig`, it only lets you set `npm config` settings like `registry` and `tag`. Sad.

In essence, our top-level `exports`, `main`, `types`, etc. now _only apply in development_, so we can point these to raw `.ts` files! TypeScript will happily parse these files, as will any modern bundler, framework, or a tool like `tsx`.

For simplicity, I've only set one field: `exports`, and I'm setting it to a simple string value. This has some benefits:

1. It's clean! You don't need to redundantly declare a big `"exports"` object in both the top-level `package.json` and `"publishConfig"`. (Though you still can if you rely on subpath imports.)
2. It's safe! By specifying `"exports"` as a single string, no subpath imports are allowed. That level of strictness is good. It means you can't use subpath imports internally that would be illegal using the configuration specified in `publishConfig`.
3. It just works at runtime. Tools like `tsx`, `esbuild`, Vite, etc. can all happily resolve this import using just the single `exports` key. You don't need `"main"` unless you're using Node.js 10 or earlier in your development environment.
4. Similarly, TypeScript is happy. I lied a bit earlier...it doesn't need a special `"types"` field. It's more than happy to fall back to `"exports"` and pull type signatures out of a regular `.ts` source file.

The big downside is the reliance on `pnpm`. That means if you ever run `npm publish` by accident, you'll accidentally publish a package that isn't runnable by Node.js 💀 You also can't rely on popular GitHub Actions like `JS-DevTools/npm-publish` since those use `npm`. This obstacle is surmountable with some tweaks to CI and diligence around publishing, but it is an important gotcha.

## 3. `"paths"` in `tsconfig.json`

TypeScript provides another way to "hijack" module resolution: the `compilerOptions.paths`.

```json
{
  "compilerOptions": {
    "paths": {
      "pkg-a": ["./packages/pkg-a/src/index.ts"],
      "pkg-b": ["./packages/pkg-b/src/index.ts"]
    }
  }
}
```

The `compilerOptions.paths` option overrides TypeScript's normal module resolution. Any import that matches a key in paths will be resolved to the corresponding file. (If you specify multiple paths, TypeScript will use the first one that exists on your file system.)

This should be added to the `tsconfig.json` for every package in your monorepo. You can avoid redundancy by having all of your package `tsconfig`s extend a shared `tsconfig.base.json`.

Remember, we also need to incorporate this into our runtime module resolution.

The popular `tsx` tool by [`@privatenumbr`](https://twitter.com/privatenumbr) [does this automatically](https://tsx.is/faq#how-does-tsx-compare-to-ts-node). This is the best way to run a TypeScript file with Node.js.

```sh
$ npm install -g tsx
$ tsx src/index.ts
```

You can also use `tsx` in conjunction with Node.js's `--import` flag.

```sh
$ npm install tsx
$ node --import tsx src/index.ts
```

In the Vite/Vitest ecosystem, there is a popular plugin to do the same called [`vite-tsconfig-paths`](https://www.npmjs.com/package/vite-tsconfig-paths).

This solution can be a bit fiddly, and requires some diligence in how you configure per-package `tsconfigs`. It should also be noted that the TypeScript team [kinda hates](https://twitter.com/andhaveaniceday/status/1770466153615577306) `tsconfig.paths`, and there are a lot of ways to shoot yourself in the foot with it.

## 4. `liveDev` mode in `tshy`

The [`tshy`](https://github.com/isaacs/tshy) (**T**ype**S**cript **Hy**bridizer) tool is an opinionated tool by the creator of `npm` that makes it simple to build ESM and CommonJS packages from your TypeScript source code.

It recently added support for a `liveDev` mode that will hardlink your TypeScript source code into `./dist/esm` and `./dist/commonjs` directories. To set this up, install `tshy` into `devDependencies`.

```sh
$ pnpm add tshy --dev
```

Add the following `"tshy"` config to your `package.json`:

```json
{
  "tshy": {
    "liveDev": true
  }
}
```

Then run `tshy` in your package directory.

```sh
$ npx tshy
```

> For simplicity, add `"tshy"` as the `"build"` script in each of your workspaces. Then you can run this script in each workspace with one command from the root of your workspace. (The exact command depends on your package manager.)

This lets VS Code discover your live TypeScript source code without any additional `package.json` configuration! And tools like TypeScript and Vitest will be able to resolve your workspace imports to the `.ts` files with no additional configuration at all!

The downside is that this requires running `tshy` in each of your workspaces packages, which starts to feel like a build step.

The upside is that you only need to do this once! Once your `src` files are hard-linked into `dist`, you can edit them like normal and those changes are automatically reflected in `dist`. (This is how hard links work.)

> The downside is that you'll need to re-run `tshy` each time you add a new TypeScript file (due to how hard links work...). Running `tshy --watch` can mitigate the "new file" problem, but for the purposes of this repo, I'm avoiding any solutions that require a file system watcher.

## 5. Custom conditions in `"exports"`

This lets you specify your TypeScript files in `package.json#exports` under a custom _[export condition](https://nodejs.org/api/packages.html#conditional-exports)_ of your choosing.

The mostly widely-utilized export conditions are `import` (for specifying ESM code), `require` (for specifying CJS code), and `types` (for specifying type definitions).

```jsonc
// package.json
{
  "name": "pkg-a",
  "exports": {
    "*": {
      "import": "./lib/index.js",
      "require": "./lib/index.cjs"
    }
  }
}
```

But you're allowed to use any string you like as a custom export condition! Export conditions are intended as an open-ended mechanism for users to specify import entrypoints for specific runtimes, bundlers, or other tooling. For instance, `"deno"`, `"bun"`, and `"workerd"` (Cloudflare Workers) all support custom conditions so libraries can ship build that are specific to those runtimes.

Here's how a custom condition might look in your `package.json`. There's nothing special about the string `"@colinhacks/zod"` here! It could be anything.

```jsonc
// package.json
{
  "name": "pkg-a",
  "exports": {
    "*": {
      "import": {
        "@colinhacks/source": "./src/index.ts", // must be first, order matters!
        "default": "./lib/index.js",
        "types": "./lib/index.d.ts"
      },
      "require": {
        "@colinhacks/source": "./src/index.ts",
        "default": "./lib/index.cjs",
        "types": "./lib/index.d.ts"
      }
    }
  }
}
```

> You should put your custom condition _first_. Order matters! It's important that your custom condition is the first one in the list (even before `"types"`).

By default, neither TypeScript nor Node.js pays attention to this new `"@colinhacks/source"` export condition. You need to tell them to incorporate it into their respective module resolution algorithms.

To tell TypeScript, add `"@colinhacks/source"` to the `customConditions` field in `tsconfig.json` for all packages in your monorepo. (You can avoid redundancy by having all of your package `tsconfig`s extend a shared `tsconfig.base.json`.)

```json
{
  "compilerOptions": {
    // include this in the tsconfig for all packages
    "customConditions": ["@colinhacks/source"]
  }
}
```

Node.js can accept custom conditions via the `--conditions` flag.

```sh
node --import=tsx --conditions=@colinhacks/source ./src/index.ts
```

In the Vite/Vitest ecosystem, this can be configured with `resolve.conditions` setting.

```js
// vite.config.json
export default {
  resolve: {
    conditions: ['@colinhacks/source'],
  },
};
```

### A note on condition naming

I chose `"@colinhacks/source"` as the condition name for the sake of uniqueness. You want to pick a condition name that will only be defined in your workspace packages _only_. If you choose something generic like `"source"`, you may have dependencies with the same condition defined in their `package.json`. In this case, VS Code will resolve imports of that package using its `"source"` files, instead of using it's pre-compiled `.d.ts` files from `"types"`. This can hurt performance of the TypeScript server and slow down your editor.

## Conclusion

Overall, my recommendation is #5: custom export conditions.

- It's clean, easy to configure, and works well with modern tooling.
- It doesn't require you to use `pnpm`, which is a non-starter for many projects.
- You don't need to worry about keeping runtime and TypeScript configurations in sync: you just set `"exports"` once using your custom condition, then tell your other tools (including TypeScript itself) to pay attention to that condition.

As usual the "comments section" for this post is on Twitter. Feel free to make comments or ask questions in the replies to this tweet:

<blockquote class="twitter-tweet"><p lang="en" dir="ltr">new blog post 👇 it breaks down a few approaches to configuring &quot;live types&quot; in TypeScript monorepos. you should never need to run `build` while developing!<br><br>1. tsconfig paths<br>2. custom export conditions<br>3. publishConfig (*my recommended solution)<a href="https://t.co/sf6F3CfcsQ">https://t.co/sf6F3CfcsQ</a></p>&mdash; Colin McDonnell (@colinhacks) <a href="https://twitter.com/colinhacks/status/1796595123595378822?ref_src=twsrc%5Etfw">May 31, 2024</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

Happy monorepo hacking!


Live types in a TypeScript monorepo

> Spoiler alert: GitHub Pages and GitHub actions are not involved.

I recently set out to build a proper documentation site for [Zod](https://github.com/colinhacks/zod) with a short and eminently reasonable list of goals:

1. The site should be generated from the README. Zod's `README.md` is the "source of truth".
2. The site should automatically update whenever the `master` branch is updated.
3. I didn't want to worry about building or maintaining a complex build workflow in GitHub Actions, if possible.



Despite the eminent reasonability, I had a hard time finding a simple solution. After a lot of research and false starts, I've found what I think is the lowest-effort, highest-reward way to publish a documentation site for your GitHub-hosted project.

Let's jump in.

## 1. Add this `index.html` to your repo

Create a file called `index.html` in your project root and paste the following contents into it.

> Replace all occurrences of `user/repo` with your project's name. And maybe write up a slightly more detailed `meta` description :)

```
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>user/repo</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta name="description" content="user/repo is cool!" />
    <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" />
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css" />
    <style>
      .markdown-section { max-width: 700px; }
    </style>
  </head>
  <body>
    <nav
      style="display: flex; flex-direction: row; align-items: center; justify-content: space-between;"
    >
      
    </nav>
    <div id="app"></div>
    <script>
      window.$docsify = {
        subMaxLevel: 1,
        maxLevel: 3,
        auto2top: true,
        repo: 'user/repo',
        routerMode: 'history',
        // homepage: "README.md"
      };
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1.28.0/prism.min.js"></script>
  </body>
</html>
```

Those 1150 bytes are doing a lot, but most importantly it's loading [Docsify](https://docsify.js.org/). Docsify is a documentation generator. You may recognize it from its goofy looking gradient cover pages with big pill-shaped buttons.

![Docsify sample homepage](/docsify.png)

> I'm not a fan of these cover pages, so we won't be using one here. All in all, though, I think Docsify is extraordinarily well designed.

It also differs from some other options like Docusaurus and Gitbook in that it's a _fully client-side_ documentation generator. Your Markdown files don't get pre-compiled to HTML ahead of time; instead, Docsify fetches it asynchronously, parses the contents in-browser, and injects the rendered HTML into the page.

_"The horror! Multiple round-trip requests before the first meaningful paint!?"_ Turns out, it's not a big issue. Modern globe-spanning ultra-fast CDNs for static content, this still feels near-instant. Google agrees; the [Zod site](https://zod.dev) gets a 98 Performance score on Lighthouse.

![98 performance on Lighthouse](/lighthouse.png)

## 2. Run locally

There's no build step required with Docsify. You could deploy your `index.html` and a `README.md` to any static site hosting service and it would work. We're going to be using [Netlify](https://www.netlify.com/) to deploy this site, but before we get to that, let's see how the site is looking. We can use Netlify's CLI to start a simple static site server.

```bash
$ npx netlify dev
◈ Netlify Dev ◈
   ┌─────────────────────────────────────────────────┐
   │                                                 │
   │   ◈ Server now ready on http://localhost:8888   │
   │                                                 │
   └─────────────────────────────────────────────────┘
```

Open `http://localhost:8888` in your browser, and you should see a rendered version of your `README.md`!

> If `netlify dev` detects that you're using a framework, this may not work. In that case you'll need to disable framework detection and tell Netlify to act as a simple static file host.
>
> ```sh
> npx netlify dev --framework "#static"
> ```

> If your primary Markdown file isn't called `README.md`, you can specify a different name with the `homepage` setting in the Docsify configuration.
>
> ```js
> window.$docsify = {
>   subMaxLevel: 1,
>   maxLevel: 3,
>   auto2top: true,
>   repo: 'user/repo',
>   routerMode: 'history',
>   homepage: 'home.md', // <-- add this
> };
> ```

## 3. Configure rewrites

Docsify using client-side routing to determine which Markdown file to load and render. In other words, it's a pure single-page application; `index.html` loads Docsify, which then assumes control over your browsers URL bar, similar to React Router or other client-side routers.

If your project/site contains several Markdown files, you may encounter a strange behavior. Consider the following file structure:

```
├── index.html
├── README.md
└── CONTRIBUTING.md
```

If you start the development server and type `localhost:8888/CONTRIBUTING` into the URL bar, you'll see a 404. That's because there's no HTML file called `CONTRIBUTING.html`. We need all incoming requests to render `index.html`! Then Docsify will read the URL and load the appropriate Markdown file.

We can achieve this with a Netlify feature called [rewrites](https://docs.netlify.com/routing/redirects/). (All static file hosts have an equivalent feature.) Create a file called `_redirects` with no extension. (With Netlify, both redirects and rewrites are declared in `_redirects`.)

```
$ touch _redirects
```

Then paste in the following:

```
/*            /             200
```

This tells Netlify that all incoming requests (`/*`) should render the homepage (`/`). However, unlike a _redirect_, rewrites do not change the URL. Basically Netlify will sneakily render `index.html` under the hood, without telling the browser.

> Another solution is to use a _hash router_. In fact, this is the default behavior for Docsify. Unfortunately, it makes the URL messy; the URL would look like `domain.com/#/CONTRIBUTING` instead of simply `domain.com/CONTRIBUTING`. I prefer clean URLs so I chose the rewrites approach.

Now when we run `npx netlify dev`, we can open `localhost:8888/CONTRIBUTING` directly without seeing a 404.

## 4. Deployment

Firebase used to be my go-to for static file hosting, but these days Netlify leads the pack on developer experience. It only takes a couple minutes to set up Github-linked static site hosting.

First, let's push our new files to `master`.

```sh
$ git add .
$ git commit -am "Add docs site"
$ git push origin master
```

Then configure Netlify.

1. Log in or create an account at [netlify.com](https://www.netlify.com/).
2. From the dashboard, click `Add new site > Import an existing project`.
3. Authenticate with GitHub (or GitLab or Bitbucket) and select your repository.

When prompted for a `"Branch to deploy"` select `master` (the default) unless your primary branch has a different name.

Under "Build settings" you can simply leave everything blank:

- `"Base directory"` — leave blank (defaults to the project root)
- `"Build command"` — leave blank (no build step necessary!)
- `"Publish directory"` — leave blank (defaults to the project root)

![Netlify configuration settings](/netlify_build.png)

There is virtually no configuration required, because we're simply hosting static files from the root directory of our `master` branch. Couldn't be easier!

> Note that we're deploying the entire contents of our repository to Netlify. You could write a build command to [delete all unwanted files](https://answers.netlify.com/t/can-i-exclude-certain-files-like-readme-md/15416) but I didn't bother. The contents of my repo are already public on the internet, so...🤷‍♂️

Proceed with the deployment. Once Netlify finishes deploying, Netlify will provide a `*.netlify.app` subdomain for your site.

## 5. Final touches

There's plenty more to do before your site is truly ready.

- Connect a custom domain
- Add a `robots.txt` to your root directory
- Add links to the top `<nav>` in `index.html`
- Add [Open Graph](https://ahrefs.com/blog/open-graph-meta-tags/) meta tags
- Add [Twitter](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup) meta tags and a banner image
- Generate a favicon ([RealFaviconGenerator](https://realfavicongenerator.net/) is great)

But I'll leave that as an exercise for the reader.

From README to documentation site in 10 minutes

In the mid-2010s, the pendulum of web development swung massively in the direction of increased type safety.

First, we all switched back to relational DBs after recovering from an embarrassingly long collective delusion that NoSQL was cool. Then TypeScript started its meteoric rise after years of quiet development. Shortly thereafter GraphQL was announced and quickly became the de facto way to implement typesafe APIs.

> TLDR: I published a new library called tRPC that makes it easy to build end-to-end typesafe APIs without code generation, by leveraging the power of modern TypeScript. To jump straight to the tRPC walkthrough, [click here](#trpc).

### GraphQL's TypeScript problem

GraphQL's biggest competitive advantage is that it's a _spec_, not a library. It's designed to be universal and language-agnostic. If you use different languages for your client and server, then by all means stick with GraphQL! It remains the best language-agnostic way to build typesafe data layers.

But the vast majority of projects that use GraphQL are JavaScript-based. The `graphql` NPM module has [5M downloads/week](https://www.npmjs.com/package/graphql) vs [~300k](https://pypistats.org/packages/graphene)) for the `graphene` Python module and [~230k](https://bestgems.org/gems/graphql) for the `graphql` Rubygem. It's not a perfect metric, but the signal is clear.

And a growing fraction of JavsScript projects are TypeScript-based. As TypeScript approaches near-universal adoption in the JS ecosystem, that means **most** GraphQL-based projects will soon be TypeScript-based (if they aren't already).

Here's the thing: most people use GraphQL as a massively over-engineered way to share the **type signature** of their API with your client. What if you could import that type signature _directly into your client_ using plain ole `import` syntax? Well...you can.

## A demonstrative example

We're going to build the world's simplest typesafe API—no codegen or GraphQL required. There's only one endpoint, with the following type signature:

`getUser(id: string) => { id: string, name: string }`

For the sake of simplicity, the API is implemented as an Express router. It should be easy to tell what's going on even if you aren't familiar with it.

### #1 Define `getUser` function

```ts
// server/routes.ts
export const getUser = async (id: string) => {
  return { id, name: 'Bilbo' };
};
```

### #2 Implement a simple RPC endpoint

We set up a special `/rpc` endpoint that accepts POST requests with a payload of type `{ endpoint: string; arguments: any[] }`. The `endpoint` property indicates the function to call (in our case, the only option is `"getUser"`). We take the `arguments` array, pass it into the appropriate function, and `res.send` the results.

```ts
// server/router.ts
import express from 'express';
import * as routes from './routes';

type Payload = { endpoint: string; arguments: any[] };

const app = express();
app.post('/rpc', async (req, res) => {
  const payload: Payload = req.body;
  if (payload.endpoint === 'getUser') {
    const user = await routes.getUser(...payload.args);
    return res.status(200).send(user);
  }

  return res.status(404).send('Endpoint not found');
});
```

> **A totally skippable aside about RPC**

> With a REST APIs, you use different URLs (`/users`, `/user/:id`) and HTTP request types (e.g GET, POST, etc) to access different functionality. For instance `GET /users` will fetch all users, `GET /user/abc123` will fetch a single user, and `POST /user` will create a new user.

> RPC strips all of that away. Endpoints are just named functions that accept some arguments and return a value. The RPC ethos is to make API calls look and feel like calling a function (albeit one that's defined on a remote server).

> GraphQL is an RPC protocol that's been augmented with a schema language and a mechanism for client-side field selection.

### #3 Import the type signature of `getUser` into the client

This is where the magic happens. We **directly import** the type signature of our API into out client. Yes, it really is this easy.

```tsx
// client/index.tsx
import type { getUser } from '../server/routes.ts';
```

Note that this works no matter where `routes.ts` lives in your file system! It could be in a different Git repo; it could be on your external hard drive. As long as the TypeScript file exists on your computer, you can import it from any other TypeScript file.

**_"But wait, I can't just import stuff from a different repo!"_**

This is often true...when you're importing code. For instance, Create React App (CRA) prohibits you from importing anything from outside of your `src` directory.

But that doesn't apply here. We're using `import type` syntax, which is a **purely static construct**. That is, it can only import _type signatures_, but not data, code, or any runtime construct. For most build systems powered by Babel (including CRA), `import type` statements (and all type annotations) just get stripped out before the bundling step.
If you're using Webpack with Babel, Parcel, or Rollup, this Just Works™. Don't believe me? Play around with this [sample repo](https://github.com/colinhacks/import-type-cra) where you can see this approach working just fine in an unejected CRA project.

You can use `import type` to import a type from any `.ts` or `.tsx` file anywhere on your filesystem. Period. This will work even if your client and server are in different repositories in different parts of your filesystem.

> Of course, if multiple developers are working on the same codebase, you'll need to standardize the relative locations of client and server repos, so relative imports work on everyone's machines. You can either establish a convention ("make sure the `server` and `client` repos are in the same folder") or use something like Git Submodules.



**_"But wait, isn't importing stuff from the server into the client a security vulnerability?!"_**

Yes—when you're importing code. But not here! Remember, we're using the `import type` syntax. It was introduced in early 2020 ([TypeScript 3.8](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export)) and it comes with a very important guarantee:

![import type never leaves remnants at runtime](/import-type.png)

All `import type` declarations are removed **completely** when you compile your TypeScript code into a JavaScript bundle, no matter what. So _yes_ — you can safely use `import type` without worrying about accidentally importing sensitive data from your server.



### #4 Make an API call

Now that we've imported the type signature of `getUser`, how do we make strongly typed API call? Answer: a bit of TypeScript magic. (Don't worry, you don't need to understand how this works! Just know that it's possible!)

```tsx
// client/index.tsx
import type { getUser } from '../server/routes.ts';

type API = {
  getUser: getUser;
  // add additional routes here...
};

const query = <Endpoint extends keyof API>(
  endpoint: Endpoint,
  ...args: Parameters<API[Endpoint]>
): ReturnType<API[Endpoint]> => {
  return fetch('http://localhost:3000/api/rpc', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ endpoint, arguments: args }),
  }).then((response) => response.json()) as any;
};
```

We now have a **fully typesafe** `query` function, which you use like this:

```ts
const user = await query('getUser', 'user_abc73bd39ef');
// => Promise<{ id: "user_abc73bd39ef", name: "Bilbo" }>
```

It's a function called `query`. The first argument is the _name_ of the
endpoint; the second is the input of the function. (As implemented each
RPC endpoint can only accept a single input.)

TypeScript validates that the endpoint name is valid...

![invalid endpoint name error](/trpc-invalid-endpoint.png)

...typechecks the arguments...

![invalid arguments](/trpc-invalid-arg.png)

...and strongly types the result.

![typed payload](/trpc-typed-payload.png)

And if you update the definition of `getUser` on your server, the new type signature **automatically** propagates to your client at the speed of TypeScript, no code generation required. The developer experience is unreal.

By using a next-generation ORM to fetch data in your endpoints, you get most of the value of GraphQL — end-to-end typesafety, easy nested fetching, field selection, etc — in a TypeScript-native way.







If you want, you can use this approach exactly as described; all the code above is available as a Next.js project in [this repo](https://github.com/colinhacks/typesafe-api-no-graphql). But there's a better way!

<a name="trpc"></a>

## Introducing tRPC!

Around 6 months ago, I distilled these ideas into a proof-of-concept library called tRPC. Since then, the inimitable [@alexdotjs](https://twitter.com/alexdotjs) has turned it into a full-fledged library. Lets see how to implement our `getUser` example with tRPC. Spoiler alert: it's mindblowingly easy.

> If you want to jump straight to the README, check it out at [github.com/trpc/trpc](github.com/trpc/trpc) — and leave a star if you're feeling generous!

### Create a router

```ts
// server/index.ts
import * as trpc from '@trpc/server';

const appRouter = trpc.router();
export type AppRouter = typeof appRouter;
```

### Add a query endpoint

Let's implement `getUser`.

```ts
// server/index.ts
import * as trpc from '@trpc/server';

export const appRouter = trpc.router().query('getUser', {
  input: String,
  async resolve(req) {
    req.input; // string
    return { id: req.input, name: 'Bilbo' };
  },
});
```

A few things to note:

- You add "endpoints" by calling the `.query` method. The first argument is a _procedure name_. The second is an object containing two properties: `input` and `resolve`.

- The `input` is a function that **validates the input**. For simplicity, all tRPC procedures accept a _single argument_. The type signature of this argument is inferred from the return type of the `input` function.

  I recommend defining your inputs using a schema definition library (I hear [Zod](https://github.com/colinhacks/zod) is pretty cool 🙃). Far too few developers rigorously validate incoming API payloads; this is a huge security risk and source of bugs. So tRPC has validation baked-in from the start.

  For simplicity, I'm just using the built-in JavaScript `String` constructor, which accepts any value and converts it into a string.

- The endpoint logic is defined in the `resolve` function. A "pseudorequest" is passed into it, which contains `input` (automatically typed as `string` in this case) and `ctx` (more on that later). tRPC **infers the return type** of your resolver. So make sure the returned value is statically typed! We recommend using a typesafe ORM like Prisma or TypeORM that automatically type the results of database operations; otherwise you'll need to write TypeScript types manually.

### What about mutations?

Like GraphQL, tRPC makes a distinction between queries and mutations. Add mutations to your router with the `mutation` method:

```ts
// server/index.ts
import * as trpc from '@trpc/server';
import { z } from 'zod';
export const appRouter = trpc
  .router()
  .query('getUser', {
    input: String,
    async resolve(req) {
      req.input; // string
      return { id: req.input, name: 'Bilbo' };
    },
  })
  .mutation('createUser', {
    input: z.object({ name: z.string() }),
    async resolve(req) {
      return await prisma.user.create({
        data: req.input,
      });
    },
  });
```

The syntax for the `mutation` is **identical** to `query`. tRPC only makes a distinction because `query` payloads are cached differently than `mutation` payloads.

### Chainable methods

Important note: when you add multiple endpoints to a router, you **must chain the calls** to `query()` and `mutation()`! This lets tRPC infer the type signature of your whole API. If you're familiar with Express you may be tempted to do this:

```ts
export const appRouter = trpc.router();

// ❌ DON'T DO THIS!! ❌

appRouter.query('getUser', {
  input: String,
  async resolve(req) {
    req.input; // string
    return { id: req.input, name: 'Bilbo' };
  },
});
```

This doesn't work at all. All router methods are `immutable`—they return an entirely new instance of `TRPCRouter`, instead of _modifying_ the current instance. So you _must chain_ these methods.

### Merging routers

At some point, you'll want to split up your tRPC router into multiple files. If all methods must be chained together, how is this possible?

tRPC provides an easy way to **merge routers**. I recommend creating a root `appRouter` and several "child routers" that you merge into it.

```ts
import { userRouter } from './routers/user';
import { postRouter } from './routers/post';

export const appRouter = trpc
  .createRouter()
  .merge('users.', userRouter) // prefix userRouter endpoints with "users."
  .merge('posts.', postRouter); // prefix postRouter endpoints with "posts."
```

All procedure names will be prefixed with the string literal you pass as the first argument of `.merge`. So a `createUser` mutation on `userRouter` will be re-named to `users.createUser`. This is made possible by the incredible _string literal templates_ feature introduced in [TypeScript 4.1](https://devblogs.microsoft.com/typescript/announcing-typescript-4-1/#template-literal-types)!

### Handing incoming requests

Now lets use our router to handle some actual HTTP requests. tRPC ships "adapters" that easily let you generate Express middleware or Next.js API routes from your tRPC router.

#### Next.js integration

```ts
// pages/api/trpc/[trpc].ts
import { createNextApiHandler } from '@trpc/server/adapters/next';

const appRouter = /* ... */;

export default createNextApiHandler({
  router: appRouter,
  createContext: (opts) => {
    return { bearer: opts.req.headers.authorization };
  },
});
```

#### Express integration

If you're using Express, do this instead:

```ts
import { createExpressMiddleware } from '@trpc/server/adapters/express';

const appRouter = /* ... */;

const app = express();

app.use(
  '/trpc',
  createExpressMiddleware({
    router: AppRouter,
    createContext: () => null, // no context
  })
);

app.listen(80);
```

#### Koa, Hapi, Nest.js

Coming soon (and PRs welcome)!

### Request context

All server adapters accept `createContext` function, where you can generate a `ctx` object from the "raw" HTTP request and response objects (available as `opts.req` and `opts.res`). This `ctx` is available in all your resolvers.

### Client-side usage

So what about the client side? The `@trpc/client` module generates a typesafe "tRPC client"—analagous to the `query` method we implemented in our toy example. You can import the the type signature of your **entire API** at once with `import type { AppRouter } from '...'`. Then pass it into `createTRPCClient`, along with the URL of your API:

```ts
// pages/index.ts
import { createTRPCClient } from '@trpc/client';
import type { AppRouter } from './api/[trpc]';

const trpcClient = createTRPCClient<AppRouter>({
  url: 'http://localhost:3000/api',
});

trpcClient.query('getUser', 'user_1238823498');
// => Promise<{ id: string; name: string }>
```

#### React integration

If you use React, you can use the `@trpc/react` package to convert your tRPC client into React hooks powered by [React Query](https://react-query.tanstack.com/). This gets you a ton of cool features like request invalidation, SSR, and cursor-based pagination! 🚀

```ts
import { createReactQueryHooks } from '@trpc/react';

// path to your backend server where your AppRouter is defined
import type { AppRouter } from '../server/trpc';

export const trpc = createReactQueryHooks<AppRouter>();
```

#### Vue and Svelte

Get in touch if you'd like to build dedicated bindings for those frameworks! Create an issue on [the GitHub repo](https://github.com/trpc/trpc).

## Wrapping up

I've been using various iterations of tRPC in production for nearly a year, and it truly feels like living in the future. I'm immensely proud of what tRPC has become. Checkout the docs (and leave a star! 🤩) on [the GitHub repo](https://github.com/trpc/trpc).

There are a lot of other features I could highlight, but that'll do for now. Huge shoutout to [@alexdotjs](https://twitter.com/alexdotjs), who picked up a fledgling proof-of-concept four months ago and carried it to the finish line!

An email regex for reasonable people

Read on

Live types in a TypeScript monorepo

From README to documentation site in 10 minutes

Building an end-to-end typesafe API — without GraphQL