typegen --watch (#12210)

* typegen: remove ts plugin

* dev: switch from chalk to picocolors

- `NO_COLOR` env var support without needing to wrap it
- 42kb -> 6kb

specifically, out-of-the-box support for `NO_COLOR` means we can remove
our `colors.ts` module and just use picocolors directly

* typegen: add `--watch` flag

* typegen: logging for --watch

* typegen: --config flag

* typegen: allow .tsx, .js, .jsx extensions for route config

* move typegen out of obsolete typescript/ dir

* refactor

* add typegen:watch script to each playground

* typesafety docs

* typegen: update decision doc

* typegen: update changeset

* typegen: update snapshot for --config flag

* pr feedback

Author: pcattori

.changeset/typesafety.md

@@ -24,16 +24,6 @@ This initial implementation targets type inference for:
 - `LoaderData` : Loader data from `loader` and/or `clientLoader` within your route module
 - `ActionData` : Action data from `action` and/or `clientAction` within your route module
 
-These types are then used to create types for route export args and props:
-
-- `LoaderArgs`
-- `ClientLoaderArgs`
-- `ActionArgs`
-- `ClientActionArgs`
-- `HydrateFallbackProps`
-- `ComponentProps` (for the `default` export)
-- `ErrorBoundaryProps`
-
 In the future, we plan to add types for the rest of the route module exports: `meta`, `links`, `headers`, `shouldRevalidate`, etc.
 We also plan to generate types for typesafe `Link`s:
 
@@ -43,109 +33,7 @@ We also plan to generate types for typesafe `Link`s:
 // typesafe `to` and `params` based on the available routes in your app
 ```
 
-#### Setup
-
-React Router will generate types into a `.react-router/` directory at the root of your app.
-This directory is fully managed by React Router and is derived based on your route config (`routes.ts`).
-
-👉 **Add `.react-router/` to `.gitignore`**
-
-```txt
-.react-router
-```
-
-You should also ensure that generated types for routes are always present before running typechecking,
-especially for running typechecking in CI.
-
-👉 **Add `react-router typegen` to your `typecheck` command in `package.json`**
-
-```json
-{
-  "scripts": {
-    "typecheck": "react-router typegen && tsc"
-  }
-}
-```
-
-To get TypeScript to use those generated types, you'll need to add them to `include` in `tsconfig.json`.
-And to be able to import them as if they files next to your route modules, you'll also need to configure `rootDirs`.
-
-👉 **Configure `tsconfig.json` for generated types**
-
-```json
-{
-  "include": [".react-router/types/**/*"],
-  "compilerOptions": {
-    "rootDirs": [".", "./.react-router/types"]
-  }
-}
-```
-
-#### `typegen` command
-
-You can manually generate types with the new `typegen` command:
-
-```sh
-react-router typegen
-```
-
-However, manual type generation is tedious and types can get out of sync quickly if you ever forget to run `typegen`.
-Instead, we recommend that you setup our new TypeScript plugin which will automatically generate fresh types whenever routes change.
-That way, you'll always have up-to-date types.
-
-#### TypeScript plugin
-
-To get automatic type generation, you can use our new TypeScript plugin.
-
-👉 **Add the TypeScript plugin to `tsconfig.json`**
-
-```json
-{
-  "compilerOptions": {
-    "plugins": [{ "name": "@react-router/dev" }]
-  }
-}
-```
-
-We plan to add some other goodies to our TypeScript plugin soon, including:
-
-- Automatic `jsdoc` for route exports that include links to official docs
-- Autocomplete for route exports
-- Warnings for non-HMR compliant exports
-
-##### VSCode
-
-TypeScript looks for plugins registered in `tsconfig.json` in the local `node_modules/`,
-but VSCode ships with its own copy of TypeScript that is installed outside of your project.
-For TypeScript plugins to work, you'll need to tell VSCode to use the local workspace version of TypeScript.
-For security reasons, [VSCode won't use the workspace version of TypeScript](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript) until you manually opt-in.
-
-Your project should have a `.vscode/settings.json` with the following settings:
-
-```json
-{
-  "typescript.tsdk": "node_modules/typescript/lib",
-  "typescript.enablePromptUseWorkspaceTsdk": true
-}
-```
-
-That way [VSCode will ask you](https://code.visualstudio.com/updates/v1_45#_prompt-users-to-switch-to-the-workspace-version-of-typescript) if you want to use the workspace version of TypeScript the first time you open a TS file in that project.
-
-> [!IMPORTANT]  
-> You'll need to install dependencies first so that the workspace version of TypeScript is available.
-
-👉 **Select "Allow" when VSCode asks if you want to use the workspace version of TypeScript**
-
-Otherwise, you can also manually opt-in to the workspace version:
-
-1. Open up any TypeScript file in your project
-2. Open up the VSCode Command Palette (<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>)
-3. Search for `Select TypeScript Version`
-4. Choose `Use Workspace Version`
-5. Quit and reopen VSCode
-
-##### Troubleshooting
+Check out our docs for more:
 
-In VSCode, open up any TypeScript file in your project and then use <kbd>CMD</kbd>+<kbd>SHIFT</kbd>+<kbd>P</kbd> to select `Open TS Server log`.
-There should be a log for `[react-router] setup` that indicates that the plugin was resolved correctly.
-Then look for any errors in the log.
+- [_Explanations > Type Safety_](https://reactrouter.com/dev/guides/explanation/type-safety)
+- [_How-To > Setting up type safety_](https://reactrouter.com/dev/guides/how-to/setting-up-type-safety)

.vscode/settings.json

@@ -167,25 +167,15 @@ import { LoaderArgs, DefaultProps } from "./+types.product";
 TypeScript will even give you import autocompletion for the typegen file and the `+` prefix helps to distinguish it as a special file.
 Big thanks to Svelte Kit for showing us that [`rootDirs` trick](https://svelte.dev/blog/zero-config-type-safety#virtual-files)!
 
-### TypeScript plugin
+### Watch mode
 
 Typegen solutions often receive criticism due to typegen'd files becoming out of sync during development.
 This happens because many typegen solutions require you to then rerun a script to update the typegen'd files.
 
-Instead, our typegen will automatically run within a TypeScript plugin.
-That means you should never need to manually run a typegen command during development.
-It also means that you don't need to run our dev server for typegen to take effect.
-The only requirement is that your editor is open.
-
-Additionally, TypeScript plugins work with any LSP-compatible editor.
-That means that this single plugin will work in VS Code, Neovim, or any other popular editor.
-
-Even more exciting is that a TS plugin sets the stage for tons of other DX goodies:
+Instead, we'll provide a `--watch` flag for the `react-router typegen` command to automatically regenerate types as files change.
+It's also straightforward to automatically run commands like `react-router typegen --watch` when opening up any modern editors.
 
-- jsdoc and links to official documentation when you hover a route export
-- Snippet-like autocomplete for route exports
-- In-editor warnings when you forget to name your React components, which would cause HMR to fail
-- ...and more...
+In the future, we may also kick off typegen watching as part of running a React Router dev server.
 
 ## Rejected solutions
 
@@ -265,6 +255,27 @@ Initially, this seemed like a good fit for React Router too, but we ran into a c
    For Svelte Kit, this isn't as big of an issue since they already need their own typecheck command for the Svelte language: `svelte-check`.
    But since React Router is pure TypeScript, it would be more natural to invoke `tsc` directly in your `package.json` scripts.
 
+### TypeScript plugin
+
+Originally, we created a basic TypeScript plugin to automatically run typegen in watch mode.
+One nice thing about this approach is that it worked across all editors.
+
+However, there were a couple drawbacks:
+
+1. A TypeScript plugin will silently fail to run unless you have installed dependencies prior to opening up the project in your editor.
+
+2. A TypeScript plugin requires your editor to use the local (workspace) version of TypeScript.
+   But by default [VSCode won't use the workspace version of TypeScript](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript), forcing you to run the `Select TypeScript Version` command every time you open up a new project.
+   You can workaround this via the `typescript.tsdk` and `typescript.enablePromptUseWorkspaceTsdk` options in `.vscode/settings.json`, but those only take effect when that _specific_ directory is opened as by VSCode.
+   For example, if you added `.vscode/settings.json` to a subfolder of a monorepo those options would be ignored when opening the root of the monorepo with VSCode.
+
+3. Debugging a TypeScript plugin is not straightforward as you need to know to run the `Open TS Server log` command in VSCode and sift through verbose logs.
+   Without this knowledge, its hard to know if you've set up typegen correctly.
+   And even if you do know this, its tedious to find out what went wrong.
+
+After we decided not to pursue "zero-effort typesafety" (as described above), our TypeScript plugin was already a simple passthrough that kicked off typegen as a side-effect.
+This was an additional indication that maybe a TypeScript plugin was not the right place for our typegen.
+
 ## Summary
 
 By leaning into automated typegen within a TypeScript plugin, we radically simplify React Router's runtime APIs while providing strong type inference across the entire framework.

decisions/0012-type-inference.md

@@ -0,0 +1,74 @@
+---
+title: Type safety
+---
+
+# Type safety
+
+React Router generates types for each route in your app that you can use to get type safety for each route module export.
+
+For example, let's say you have a `products/:id` route configured:
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+
+export const routes: RouteConfig = [
+  route("products/:id", "./routes/product.tsx"),
+];
+```
+
+You can import route-specific types like so:
+
+```tsx filename=app/routes/product.tsx
+import type * as Route from "./+types.product";
+// types generated for this route 👆
+
+export function loader({ params }: Route.LoaderArgs) {
+  //                      👆 { id: string }
+  return { planet: `world #${params.id}` };
+}
+
+export default function Component({
+  loaderData, // 👈 { planet: string }
+}: Route.ComponentProps) {
+  return <h1>Hello, {loaderData.planet}!</h1>;
+}
+```
+
+If you haven't done so already, check out our guide for [setting up type safety][setting-up-type-safety] in a new project.
+
+## `typegen` command
+
+You can manually generate types with the `typegen` command:
+
+```sh
+react-router typegen
+```
+
+You can also use `--watch` to automatically regenerate types as files change:
+
+```sh
+react-router typegen --watch
+```
+
+The following types are generated for each route:
+
+- `LoaderArgs`
+- `ClientLoaderArgs`
+- `ActionArgs`
+- `ClientActionArgs`
+- `HydrateFallbackProps`
+- `ComponentProps` (for the `default` export)
+- `ErrorBoundaryProps`
+
+## How it works
+
+React Router's type generation executes your route config (`app/routes.ts` by default) to determine the routes for your app.
+It then generates a `+types.<route file>.d.ts` for each route within a special `.react-router/types/` directory.
+With [`rootDirs` configured][setting-up-type-safety], TypeScript can import these generated files as if they were right next to their corresponding route modules.
+
+For a deeper dive into some of the design decisions, check out our [type inference decision doc](https://github.com/remix-run/react-router/blob/dev/decisions/0012-type-inference.md).
+
+[setting-up-type-safety]: ../how-to/setting-up-type-safety.md

docs/explanation/type-safety.md

@@ -0,0 +1,95 @@
+---
+title: Setting up type safety
+---
+
+To know more about how type safety works in React Router, check out our [dedicated explanation](../explanation//type-safety.md).
+
+# Setting up type safety
+
+React Router generates types into a `.react-router/` directory at the root of your app.
+This directory is fully managed by React Router and is derived from your route config (`app/routes.ts` by default), so it should be gitignore'd.
+
+👉 **Add `.react-router/` to `.gitignore`**
+
+```txt
+.react-router/
+```
+
+Make sure generated types are always present before type checking,
+especially when running type checking in CI.
+
+👉 **Add `react-router typegen` to your `typecheck` command in `package.json`**
+
+```json
+{
+  "scripts": {
+    "typecheck": "react-router typegen && tsc"
+  }
+}
+```
+
+To get TypeScript to use those generated types, you'll need to add them to `include` in `tsconfig.json`.
+And to be able to import them as if they files next to your route modules, you'll also need to [configure `rootDirs`](https://www.typescriptlang.org/tsconfig/#rootDirs).
+
+👉 **Configure `tsconfig.json` for generated types**
+
+```json
+{
+  "include": [".react-router/types/**/*"],
+  "compilerOptions": {
+    "rootDirs": [".", "./.react-router/types"]
+  }
+}
+```
+
+During development, its nice to have a dedicate `package.json` script to run type generation in watch mode.
+
+👉 **Add a `typegen --watch` script** (optional)
+
+```json filename=package.json
+{
+  "scripts": {
+    "typegen:watch": "react-router typegen --watch"
+  }
+}
+```
+
+## Automatic typegen in VSCode (optional)
+
+If you'd rather not need to remember to run `react-router typegen --watch` every time you start working on your app, you can use [VSCode Tasks](https://code.visualstudio.com/docs/editor/tasks) to automate this.
+Let's make use of the `typegen:watch` script you added earlier.
+
+👉 **Configure a VSCode task for `typegen:watch`**
+
+```json filename=.vscode/tasks.json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "React Router: Typegen",
+      "type": "shell",
+      "command": "npm run typegen:watch",
+      "problemMatcher": [],
+      "isBackground": true,
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "dedicated"
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
+    }
+  ]
+}
+```
+
+<docs-info>
+
+You should create `.vscode/tasks.json` in the directory you plan to open with VSCode.
+For monorepos, you can create this file in the repo root and use the [`cwd` option for the task](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks) to run the command within a subfolder.
+
+</docs-info>
+
+Now, VSCode will automatically run the `typegen:watch` script in a dedicated terminal anytime you open your project.

docs/how-to/setting-up-type-safety.md

@@ -120,6 +120,9 @@ describe("remix CLI", () => {
           \`reveal\` Options:
             --config, -c        Use specified Vite config file (string)
             --no-typescript     Generate plain JavaScript files
+          \`typegen\` Options:
+            --config, -c        Use specified Vite config file (string)
+            --watch             Automatically regenerate types whenever route config (\`routes.ts\`) or route modules change
 
           Build your project:
 
@@ -146,7 +149,9 @@ describe("remix CLI", () => {
 
           Generate types for route modules:
 
-           $ react-router typegen"
+           $ react-router typegen
+           $ react-router typegen --watch
+           $ react-router typegen --config vite.react-router.config.ts"
       `);
     });
   });