docs(solid-router): router-monorepo-simple-lazy example (#5853)

* docs(solid-router): router-monorepo-simple-lazy example

* lockfile

* ci: apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: birkskyum

docs/router/config.json

@@ -686,6 +686,10 @@
               "label": "Monorepo basic",
               "to": "framework/solid/examples/router-monorepo-simple"
             },
+            {
+              "label": "Monorepo basic (with lazy loading)",
+              "to": "framework/solid/examples/router-monorepo-simple-lazy"
+            },
             {
               "label": "Monorepo with Solid Query",
               "to": "framework/solid/examples/router-monorepo-solid-query"

examples/solid/router-monorepo-simple-lazy/.gitignore

@@ -0,0 +1,13 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+*.js
+
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+
+pnpm-workspace.yaml

examples/solid/router-monorepo-simple-lazy/.stackblitzrc

@@ -0,0 +1,3 @@
+{
+  "startCommand": "cp pnpm-workspace.yaml.example pnpm-workspace.yaml && pnpm install && pnpm dev"
+}

examples/solid/router-monorepo-simple-lazy/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "search.exclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "files.readonlyInclude": {
+    "**/routeTree.gen.ts": true
+  }
+}

examples/solid/router-monorepo-simple-lazy/README.md

@@ -0,0 +1,38 @@
+# Example of a monorepo with router and feature libraries, using lazy loading
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm dev` or `yarn dev`
+
+A challenge with TanStack Router in a monorepo setup is that it requires TypeScript type augmentations. However, if you set this up directly in the final app, the links inside the libraries won’t be type-safe. To solve this in a monorepo, you need a separate library just for the router, without any components, and then integrate it with the app.
+
+This example showcases this approach using the following packages:
+
+- `packages/router` is the router library
+- `packages/post-feature` is the posts UI library
+- `packages/app` is the app
+
+With this approach, we can use loaders in the router and the feature library without creating circular dependencies.
+
+Since the router library re-exports the router components, importing them in the feature library ensures they remain type-safe, as they’re linked to the TypeScript augmentations.
+
+Finally, in the app, we can create a map of routes to components ([`packages/app/src/main.tsx`](./packages/app/src/main.tsx)), which ties the router to the components.
+
+## How lazy loading works
+
+Eath feature exports a `createLazyRoute` function that returns a lazy route. This lazy route is then used in the router map to bind the lazy route to the actual route. This allows library to define their component, pending, error and nod found components directly.
+
+The types on the ([`packages/app/src/main.tsx`](./packages/app/src/main.tsx)) are used to map the route to the lazy route, and enforce they match the route path.
+
+**Note: if you match a lazy route with a different id of the route, you will get a runtime error, hence the mapped types to ensure we are also warned by typescript.**
+
+Here is what it looks like in the monorepo:
+
+![graph](./assets/graph.png)
+
+## Stackblitz limitation
+
+### Typescript IDE feedback
+
+Due to a limitation on Stackblitz, the example's types are not properly inferred in the IDE, however as soon as you click on fork in the bottom right corner, the types should be correctly inferred.

examples/solid/router-monorepo-simple-lazy/assets/graph.png

@@ -0,0 +1,27 @@
+{
+  "name": "router-solid-mono-simple-lazy",
+  "version": "1.0.0",
+  "scripts": {
+    "post-feature": "pnpm --filter @router-solid-mono-simple-lazy/post-feature",
+    "router": "pnpm --filter @router-solid-mono-simple-lazy/router",
+    "app": "pnpm --filter @router-solid-mono-simple-lazy/app",
+    "dev": "pnpm router build && pnpm post-feature build && pnpm app dev"
+  },
+  "dependencies": {
+    "@tanstack/solid-router": "^1.135.2",
+    "@tanstack/solid-router-devtools": "^1.135.2",
+    "@tanstack/router-plugin": "^1.135.2",
+    "solid-js": "^1.9.10",
+    "redaxios": "^0.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "vite-plugin-solid": "^2.11.10",
+    "typescript": "^5.7.2",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC"
+}

examples/solid/router-monorepo-simple-lazy/package.json

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

examples/solid/router-monorepo-simple-lazy/packages/app/index.html

@@ -0,0 +1,38 @@
+{
+  "name": "@router-solid-mono-simple-lazy/app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port=3001",
+    "build": "vite build && tsc --noEmit",
+    "serve": "vite preview",
+    "start": "vite"
+  },
+  "dependencies": {
+    "@router-solid-mono-simple-lazy/post-feature": "workspace:*",
+    "@router-solid-mono-simple-lazy/router": "workspace:*",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "@tanstack/solid-router-devtools": "^1.135.2",
+    "postcss": "^8.5.1",
+    "autoprefixer": "^10.4.20",
+    "tailwindcss": "^3.4.17",
+    "vite": "^7.1.7",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "nx": {
+    "targets": {
+      "dev": {
+        "dependsOn": [
+          "^build"
+        ]
+      }
+    }
+  }
+}

examples/solid/router-monorepo-simple-lazy/packages/app/package.json

@@ -0,0 +1,50 @@
+import { render } from 'solid-js/web'
+import { RouterProvider } from '@tanstack/solid-router'
+import { router } from '@router-solid-mono-simple-lazy/router'
+import { RootComponent } from './rootComponent'
+import type {
+  RouteById,
+  RouterIds,
+} from '@router-solid-mono-simple-lazy/router'
+import type { LazyRoute } from '@tanstack/solid-router'
+import './style.css'
+
+// Generic to enforce that the route returned matches the route path
+type LazyRouteFn<TRoutePath extends RouterIds> = () => Promise<
+  LazyRoute<RouteById<(typeof router)['routeTree'], TRoutePath>>
+>
+
+type RouterMap = {
+  // __root__ is a special route that isn't lazy loaded, so we need to manually bind it
+  // You could consider adding null to the returned type to have routes without rendering
+  [K in Exclude<RouterIds, '__root__'>]: LazyRouteFn<K>
+}
+
+const routerMap: RouterMap = {
+  '/': () =>
+    import('@router-solid-mono-simple-lazy/post-feature/post-list').then(
+      (d) => d.PostRoute,
+    ),
+  '/$postId': () =>
+    import('@router-solid-mono-simple-lazy/post-feature/post-id-page').then(
+      (d) => d.PostIdRoute,
+    ),
+}
+
+// Given __root__ is a special route that isn't lazy loaded, we need to update it manually
+router.routesById['__root__'].update({
+  component: RootComponent,
+})
+
+Object.entries(routerMap).forEach(([path, component]) => {
+  const foundRoute = router.routesById[path as RouterIds]
+  // Bind the lazy route to the actual route
+  foundRoute.lazy(component)
+})
+
+// Render the app
+const rootElement = document.getElementById('app')!
+
+if (!rootElement.innerHTML) {
+  render(() => <RouterProvider router={router} />, rootElement)
+}