@depup/nitro 3.0.260311-beta-depup.0

package/skills/nitro/docs/examples/vite-ssr-tss-react.md

@@ -0,0 +1,444 @@
+# SSR with TanStack Start
+
+> Full-stack React with TanStack Start in Nitro using Vite.
+
+<code-tree>
+
+```json [package.json]
+{
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite dev",
+    "start": "node .output/server/index.mjs"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "^1.158.1",
+    "@tanstack/react-router-devtools": "^1.158.1",
+    "@tanstack/react-start": "^1.158.3",
+    "nitro": "latest",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwind-merge": "^3.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/node": "latest",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.3",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3",
+    "vite": "beta",
+    "vite-tsconfig-paths": "^6.0.5"
+  }
+}
+```
+
+```ts [server.ts]
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
+
+export default createServerEntry({
+  fetch(request) {
+    return handler.fetch(request);
+  },
+});
+```
+
+```json [tsconfig.json]
+{
+  "extends": "nitro/tsconfig",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "jsx": "react-jsx",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  }
+}
+```
+
+```js [vite.config.mjs]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
+import viteTsConfigPaths from "vite-tsconfig-paths";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [
+    viteTsConfigPaths({ projects: ["./tsconfig.json"] }),
+    tanstackStart(),
+    viteReact(),
+    tailwindcss(),
+    nitro(),
+  ],
+  environments: {
+    ssr: { build: { rollupOptions: { input: "./server.ts" } } },
+  },
+});
+```
+
+```tsx [src/router.tsx]
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen.ts";
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    defaultPreload: "intent",
+    defaultErrorComponent: () => <div>Internal Server Error</div>,
+    defaultNotFoundComponent: () => <div>Not Found</div>,
+    scrollRestoration: true,
+  });
+  return router;
+}
+```
+
+```ts [src/routeTree.gen.ts]
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as ApiTestRouteImport } from './routes/api/test'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiTestRoute = ApiTestRouteImport.update({
+  id: '/api/test',
+  path: '/api/test',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/api/test': typeof ApiTestRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/api/test': typeof ApiTestRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/api/test': typeof ApiTestRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/api/test'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/api/test'
+  id: '__root__' | '/' | '/api/test'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ApiTestRoute: typeof ApiTestRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/test': {
+      id: '/api/test'
+      path: '/api/test'
+      fullPath: '/api/test'
+      preLoaderRoute: typeof ApiTestRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ApiTestRoute: ApiTestRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}
+```
+
+```tsx [src/routes/__root.tsx]
+/// <reference types="vite/client" />
+import { HeadContent, Link, Scripts, createRootRoute } from "@tanstack/react-router";
+import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
+import * as React from "react";
+import appCss from "~/styles/app.css?url";
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+    ],
+    links: [{ rel: "stylesheet", href: appCss }],
+    scripts: [{ src: "/customScript.js", type: "text/javascript" }],
+  }),
+  errorComponent: () => <h1>500: Internal Server Error</h1>,
+  notFoundComponent: () => <h1>404: Page Not Found</h1>,
+  shellComponent: RootDocument,
+});
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <div className="p-2 flex gap-2 text-lg">
+          <Link to="/" activeProps={{ className: "font-bold" }} activeOptions={{ exact: true }}>
+            Home
+          </Link>{" "}
+          <Link
+            // @ts-ignore
+            to="/this-route-does-not-exist"
+            activeProps={{ className: "font-bold" }}
+          >
+            404
+          </Link>
+        </div>
+        <hr />
+        {children}
+        <TanStackRouterDevtools position="bottom-right" />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx [src/routes/index.tsx]
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/")({ component: Home });
+
+function Home() {
+  return (
+    <div className="p-2">
+      <h3>Welcome Home!</h3>
+      <a href="/api/test">/api/test</a>
+    </div>
+  );
+}
+```
+
+```css [src/styles/app.css]
+@import "tailwindcss";
+
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentcolor);
+  }
+}
+
+@layer base {
+  html {
+    color-scheme: light dark;
+  }
+
+  * {
+    @apply border-gray-200 dark:border-gray-800;
+  }
+
+  html,
+  body {
+    @apply text-gray-900 bg-gray-50 dark:bg-gray-950 dark:text-gray-200;
+  }
+
+  .using-mouse * {
+    outline: none !important;
+  }
+}
+```
+</code-tree>
+
+Set up TanStack Start with Nitro for a full-stack React framework experience with server-side rendering, file-based routing, and integrated API routes.
+
+## Overview
+
+1. Add the Nitro Vite plugin to your Vite config
+2. Create a server entry using TanStack Start's server handler
+3. Configure the router with default components
+4. Define routes and API endpoints using file-based routing
+
+## 1. Configure Vite
+Add the Nitro, React, TanStack Start, and Tailwind plugins to your Vite config:
+
+```js [vite.config.mjs]
+import { defineConfig } from "vite";
+import { nitro } from "nitro/vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import viteReact from "@vitejs/plugin-react";
+import viteTsConfigPaths from "vite-tsconfig-paths";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [
+    viteTsConfigPaths({ projects: ["./tsconfig.json"] }),
+    tanstackStart(),
+    viteReact(),
+    tailwindcss(),
+    nitro(),
+  ],
+  environments: {
+    ssr: { build: { rollupOptions: { input: "./server.ts" } } },
+  },
+});
+```
+
+The `tanstackStart()` plugin provides full SSR integration with automatic client entry handling. Use `viteTsConfigPaths()` to enable path aliases like `~/` from tsconfig. The `environments.ssr` option points to the server entry file.
+
+## 2. Create the Server Entry
+
+Create a server entry that uses TanStack Start's handler:
+
+```ts [server.ts]
+import handler, { createServerEntry } from "@tanstack/react-start/server-entry";
+
+export default createServerEntry({
+  fetch(request) {
+    return handler.fetch(request);
+  },
+});
+```
+
+TanStack Start handles SSR automatically. The `createServerEntry` wrapper integrates with Nitro's server entry format, and the `handler.fetch` processes all incoming requests.
+
+## 3. Configure the Router
+
+Create a router factory function with default error and not-found components:
+
+```tsx [src/router.tsx]
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen.ts";
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    defaultPreload: "intent",
+    defaultErrorComponent: () => <div>Internal Server Error</div>,
+    defaultNotFoundComponent: () => <div>Not Found</div>,
+    scrollRestoration: true,
+  });
+  return router;
+}
+```
+
+The router factory configures preloading behavior, scroll restoration, and default error/not-found components.
+
+## 4. Create the Root Route
+
+The root route defines your HTML shell with head management and scripts:
+
+```tsx [src/routes/__root.tsx]
+/// <reference types="vite/client" />
+import { HeadContent, Link, Scripts, createRootRoute } from "@tanstack/react-router";
+import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
+import * as React from "react";
+import appCss from "~/styles/app.css?url";
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+    ],
+    links: [{ rel: "stylesheet", href: appCss }],
+    scripts: [{ src: "/customScript.js", type: "text/javascript" }],
+  }),
+  errorComponent: () => <h1>500: Internal Server Error</h1>,
+  notFoundComponent: () => <h1>404: Page Not Found</h1>,
+  shellComponent: RootDocument,
+});
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <div className="p-2 flex gap-2 text-lg">
+          <Link to="/" activeProps={{ className: "font-bold" }} activeOptions={{ exact: true }}>
+            Home
+          </Link>{" "}
+          <Link
+            // @ts-ignore
+            to="/this-route-does-not-exist"
+            activeProps={{ className: "font-bold" }}
+          >
+            404
+          </Link>
+        </div>
+        <hr />
+        {children}
+        <TanStackRouterDevtools position="bottom-right" />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+
+Define meta tags, stylesheets, and scripts in the `head()` function. The `shellComponent` provides the HTML document shell that wraps all pages. Use `HeadContent` to render the head configuration and `Scripts` to inject the client-side JavaScript for hydration.
+
+## 5. Create Page Routes
+
+Page routes define your application pages:
+
+```tsx [src/routes/index.tsx]
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/")({ component: Home });
+
+function Home() {
+  return (
+    <div className="p-2">
+      <h3>Welcome Home!</h3>
+      <a href="/api/test">/api/test</a>
+    </div>
+  );
+}
+```
+
+## API Routes
+
+TanStack Start supports API routes alongside page routes. Create files in `src/routes/api/` to define server endpoints that Nitro serves automatically.
+
+## Learn More
+
+- [TanStack Start Documentation](https://tanstack.com/start)
+- [Server Entry](/docs/server-entry)