experiment(web): migrate from Next.js to TanStack Start

.env.example

@@ -17,7 +17,7 @@ SESSION_SECRET='please-generate-a-secret-and-put-it-here'
 
 # Change this to your app name. This is used when the application needs to refer to itself,
 # e.g. in emails or on the landing page.
-NEXT_PUBLIC_APP_NAME='Starter Kit'
+VITE_APP_NAME='Starter Kit'
 
 # Sets the debug level for logging. Can be one of: silent, error, warn, info, debug, trace
 LOG_LEVEL="debug"

.github/dependabot.yml

@@ -13,11 +13,6 @@ updates:
         patterns:
           - 'prisma'
           - '@prisma/*'
-      next:
-        applies-to: version-updates
-        patterns:
-          - '@next/*'
-          - 'next'
       react:
         applies-to: version-updates
         patterns:

.gitignore

@@ -9,11 +9,6 @@ node_modules
 coverage
 **/test-results
 
-# next.js
-.next/
-out/
-next-env.d.ts
-
 # production
 build
 

.oxfmtrc.jsonc

@@ -1,6 +1,6 @@
 {
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": ["turbo/generators/templates/**/*.hbs"],
+  "ignorePatterns": ["turbo/generators/templates/**/*.hbs", "apps/web/src/routeTree.gen.ts"],
   "printWidth": 80,
   "semi": false,
   "singleQuote": true,
@@ -38,13 +38,13 @@
         "modifiers": ["value"],
       },
       {
-        "elementNamePattern": ["next", "next/*"],
-        "groupName": "next-types",
+        "elementNamePattern": ["@tanstack/react-start", "@tanstack/react-start/*", "@tanstack/react-router", "@tanstack/react-router/*"],
+        "groupName": "tanstack-types",
         "selector": "type",
       },
       {
-        "elementNamePattern": ["next", "next/*"],
-        "groupName": "next-values",
+        "elementNamePattern": ["@tanstack/react-start", "@tanstack/react-start/*", "@tanstack/react-router", "@tanstack/react-router/*"],
+        "groupName": "tanstack-values",
         "selector": "external",
         "modifiers": ["value"],
       },
@@ -63,8 +63,8 @@
     "groups": [
       "react-types",
       "react-values",
-      "next-types",
-      "next-values",
+      "tanstack-types",
+      "tanstack-values",
       "builtin",
       "external",
       "acme-types",

.vscode/settings.json

@@ -6,42 +6,40 @@
   "editor.formatOnSave": true,
   "editor.formatOnPaste": false,
   "editor.codeActionsOnSave": {
-    "source.fixAll.oxc": "always"
+    "source.fixAll.oxc": "always",
   },
   "oxc.typeAware": true,
   "tailwindCSS.classFunctions": ["cva", "cx", "cn"],
   "tailwindCSS.experimental.classRegex": [
     ":\\s*?[\"'`]([^\"'`]*).*?,",
     [
       "classNames:\\s*{([\\s\\S]*?)}",
-      "\\s?[\\w].*:\\s*?[\"'`]([^\"'`]*).*?,?\\s?"
+      "\\s?[\\w].*:\\s*?[\"'`]([^\"'`]*).*?,?\\s?",
     ],
     ["classNames={{([^}]*)}}", "[\"'`]([^\"'`]*)[\"'`]"],
     [
       "tv\\(([^)(]*(?:\\([^)(]*(?:\\([^)(]*(?:\\([^)(]*\\)[^)(]*)*\\)[^)(]*)*\\)[^)(]*)*)\\)",
-      "\"(.*?)\""
+      "\"(.*?)\"",
     ],
-    ["class:\\s*?[\"'`]([^\"'`]*).*?,"]
+    ["class:\\s*?[\"'`]([^\"'`]*).*?,"],
   ],
   "files.associations": {
     "**/tooling/typescript/*.json": "jsonc",
     "**/tsconfig.json": "jsonc",
     "**/tsconfig.*.json": "jsonc",
-    "*.css": "tailwindcss"
+    "*.css": "tailwindcss",
   },
   "typescript.preferences.autoImportFileExcludePatterns": [
     "zod/dist/types/index.d.ts", // Force auto-imports to v4
-    "next/router.d.ts",
-    "next/dist/client/router.d.ts",
-    "tailwind-variants/dist/index.d.ts" // Force imports from oui-theme instead
+    "tailwind-variants/dist/index.d.ts", // Force imports from oui-theme instead
   ],
   "json.schemas": [
     {
       "fileMatch": ["task-definition.json"],
-      "url": "https://ecs-intellisense.s3-us-west-2.amazonaws.com/task-definition/schema.json"
-    }
+      "url": "https://ecs-intellisense.s3-us-west-2.amazonaws.com/task-definition/schema.json",
+    },
   ],
   "[prisma]": {
-    "editor.defaultFormatter": "Prisma.prisma"
-  }
+    "editor.defaultFormatter": "Prisma.prisma",
+  },
 }

README.md

@@ -9,7 +9,7 @@ A technical kit to quickly build new products from
 
 - 🗼 Monorepo setup with [Turborepo](https://turborepo.com)
 - 🧙‍♂️ E2E typesafety with [tRPC v11](https://trpc.io)
-- ⚡ Full-stack React with [Next.js v15](https://nextjs.org)
+- ⚡ Full-stack React with [TanStack Start](https://tanstack.com/start)
 - 🌈 Database with [Prisma](https://www.prisma.io/)
 - ⚙️ VSCode extensions
 - 🎨 Oxlint + Oxfmt
@@ -33,7 +33,7 @@ A technical kit to quickly build new products from
   └─ Oxfmt formatter configuration
 apps
   └─ web
-      ├─ Next.js 15
+      ├─ TanStack Start
       ├─ React 19
       ├─ Tailwind CSS v4
       └─ E2E Typesafe API Server & Client
@@ -112,9 +112,9 @@ If not set, OTP emails will be logged to the console instead.
 
 #### Retrieving client-side environment variables in code
 
-⚠️ When adding client-only environment variables in NextJS, you must prefix the variable with `NEXT_PUBLIC_` to ensure that the variable is exposed to the browser. For example, if you want to add a variable called `MY_ENV_VAR`, you should add it to your `.env` file as `NEXT_PUBLIC_MY_ENV_VAR`.
+⚠️ When adding client-only environment variables, you must prefix the variable with `VITE_` to ensure that the variable is exposed to the browser. For example, if you want to add a variable called `MY_ENV_VAR`, you should add it to your `.env` file as `VITE_MY_ENV_VAR`.
 
-You will also need to update the various environment files (like [apps/web/src/env.ts](apps/web/src/env.ts#L5) or [packages/db/src/env.ts](packages/db/src/env.ts#L6)) to explicitly reference the variable so NextJS will correctly bundle the environment variable into the client-side bundle.
+You will also need to update the various environment files (like [apps/web/src/env.ts](apps/web/src/env.ts) or [packages/db/src/env.ts](packages/db/src/env.ts)) to explicitly reference the variable so it is correctly bundled into the client-side bundle.
 
 ### 2. Adding a new package
 
@@ -141,9 +141,9 @@ and tutorials, can be found [here](https://start.open.gov.sg).
 
 ### Deploy to Vercel
 
-Let's deploy the Next.js application to [Vercel](https://vercel.com). If you've never deployed a Turborepo app there, don't worry, the steps are quite straightforward. You can also read [the official Turborepo guide](https://vercel.com/docs/concepts/monorepos/turborepo) on deploying to Vercel.
+Let's deploy the TanStack Start application to [Vercel](https://vercel.com). If you've never deployed a Turborepo app there, don't worry, the steps are quite straightforward. You can also read [the official Turborepo guide](https://vercel.com/docs/concepts/monorepos/turborepo) on deploying to Vercel.
 
-1. Create a new project on Vercel, select the `apps/web` folder as the root directory. Vercel's zero-config system should handle all configurations for you.
+1. Create a new project on Vercel, select the `apps/web` folder as the root directory. Set the build command to `pnpm vercel-build` and the output directory to `.output`.
 
 2. Add the prerequisite environment variables outlined in the [Prerequisites](#prerequisites) section.
 

apps/web/.oxlintrc.json

@@ -4,7 +4,7 @@
     "typeAware": true,
     "reportUnusedDisableDirectives": "off"
   },
-  "ignorePatterns": ["*.config.*"],
+  "ignorePatterns": ["*.config.*", "src/routeTree.gen.ts"],
   "overrides": [
     {
       "files": ["**/*.{js,ts,tsx}"],

apps/web/.storybook/decorators.tsx

@@ -1,18 +1,29 @@
 import { useState } from 'react'
 
-import type { Decorator } from '@storybook/nextjs-vite'
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRouter,
+} from '@tanstack/react-router'
+
+import type { Decorator } from '@storybook/react-vite'
 import {
   defaultShouldDehydrateQuery,
   QueryClient,
   QueryClientProvider,
 } from '@tanstack/react-query'
 import { createTRPCClient, httpLink, loggerLink } from '@trpc/client'
-import { NuqsAdapter } from 'nuqs/adapters/next/app'
+import { NuqsAdapter } from 'nuqs/adapters/react'
 import SuperJSON from 'superjson'
 
 import type { AppRouter } from '~/server/api/root'
 import { TRPCProvider } from '~/trpc/react'
 
+export const storybookRouter = createRouter({
+  routeTree: createRootRoute().addChildren([]),
+  history: createMemoryHistory({ initialEntries: ['/'] }),
+})
+
 /**
  * This decorator wraps stories with TRPC and React Query and the other app-level providers.
  * It mimics the setup in `apps/web/src/app/provider.tsx` and `apps/web/src/app/layout.tsx`.

apps/web/.storybook/main.ts

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module'
 import { dirname, join } from 'path'
 
-import type { StorybookConfig } from '@storybook/nextjs-vite'
+import type { StorybookConfig } from '@storybook/react-vite'
 
 const require = createRequire(import.meta.url)
 
@@ -13,25 +13,37 @@ function getAbsolutePath(value: string): string {
   return dirname(require.resolve(join(value, 'package.json')))
 }
 const config: StorybookConfig = {
-  features: {
-    experimentalRSC: true,
-  },
   stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
   addons: [
     getAbsolutePath('@storybook/addon-docs'),
     getAbsolutePath('@storybook/addon-a11y'),
     getAbsolutePath('@storybook/addon-vitest'),
   ],
   framework: {
-    name: getAbsolutePath('@storybook/nextjs-vite'),
+    name: getAbsolutePath('@storybook/react-vite'),
     options: {},
   },
   async viteFinal(config) {
-    // TailwindCSS is not being imported properly within Storybook, so we add the
-    // TailwindCSS plugin to Vite directly here.
     const { default: tailwindcss } = await import('@tailwindcss/vite')
     const { mergeConfig } = await import('vite')
-    return mergeConfig(config, { plugins: [tailwindcss()] })
+    // TanStack Start plugins (pulled from vite.config.ts) conflict with
+    // Storybook's multi-entry build under Rolldown (Vite 8). Storybook stories
+    // only need React component context, not TanStack Start routing.
+    const filteredConfig = {
+      ...config,
+      plugins: (config.plugins ?? [])
+        .flat(Infinity as 1)
+        .filter(
+          (p: unknown) =>
+            !p || !(p as { name?: string }).name?.startsWith('tanstack')
+        ),
+    }
+    return mergeConfig(filteredConfig, {
+      plugins: [tailwindcss()],
+      define: {
+        'process.env': {},
+      },
+    })
   },
   staticDirs: ['../public'],
 }

apps/web/.storybook/preview.ts → apps/web/.storybook/preview.tsx

@@ -1,9 +1,12 @@
-import type { Preview } from '@storybook/nextjs-vite'
+import { RouterContextProvider } from '@tanstack/react-router'
+
+import type { Preview } from '@storybook/react-vite'
 import { initialize, mswLoader } from 'msw-storybook-addon'
 
 import { viewport } from '@acme/storybook-config'
 
-import { ibmPlexMono, inter } from '~/lib/fonts'
+import { storybookRouter } from './decorators'
+
 import '../src/app/globals.css'
 
 // Initialize MSW
@@ -13,9 +16,6 @@ initialize({
 
 const preview: Preview = {
   parameters: {
-    nextjs: {
-      appDirectory: true,
-    },
     layout: 'fullscreen',
     viewport,
     chromatic: {
@@ -32,13 +32,15 @@ const preview: Preview = {
     (Story) => {
       // Apply the same font classes as the main app
       document.documentElement.classList.add(
-        ibmPlexMono.variable,
-        inter.variable,
         'text-base-content-default',
         'font-sans',
         'antialiased'
       )
-      return Story()
+      return (
+        <RouterContextProvider router={storybookRouter}>
+          <Story />
+        </RouterContextProvider>
+      )
     },
   ],
   loaders: [mswLoader],