typesafety docs

Author: pcattori

docs/discussion/type-safety.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"),
+];
+```
+
+Then, 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]: ../guides/setting-up-type-safety.md

docs/guides/setting-up-type-safety.md

@@ -0,0 +1,85 @@
+---
+title: Setting up type safety
+---
+
+To know more about how type safety works in React Router, check out our [dedicated explanation](../discussion/type-safety.md).
+
+# Setting up type safety
+
+React Router generates types for 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/
+```
+
+You should also ensure that generated types 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`](https://www.typescriptlang.org/tsconfig/#rootDirs).
+
+👉 **Configure `tsconfig.json` for generated types**
+
+```json
+{
+  "include": [".react-router/types/**/*"],
+  "compilerOptions": {
+    "rootDirs": [".", "./.react-router/types"]
+  }
+}
+```
+
+## 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.
+
+👉 **Add a `typegen:watch` script**
+
+```json filename=package.json
+{
+  "scripts": {
+    "typegen:watch": "react-router typegen --watch"
+  }
+}
+```
+
+👉 **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"
+      }
+    }
+  ]
+}
+```
+
+Now, VSCode will automatically run the `typegen:watch` script in a dedicated terminal anytime you open your project.