slug: docs/web-app-shell-routing.md scope: web app shell, TanStack routing entrypoints, root/home routes, styling, public app configuration, and deployment/build config that shapes the web application covers:
- apps/web/src/router.tsx
- apps/web/src/routeTree.gen.ts
- apps/web/src/routes/__root.tsx
- apps/web/src/routes/index.tsx
- apps/web/src/styles.css
- apps/web/public/**
- apps/web/*.json
- apps/web/*.ts
- apps/web/*.jsonc
- apps/web/moon.yml
Web App Shell and Routing
Overview
The web app is a TanStack Start React application built around file-based TanStack Router routes. apps/…/router.tsx is the router factory: it imports the generated routeTree from apps/…/routeTree.gen.ts, enables scroll restoration, and uses intent-based preloading with defaultPreloadStaleTime: 0. The module augmentation in the same file registers the return type of getRouter() with @tanstack/react-router, so route APIs in the app are typed against this router instance.
apps/…/routeTree.gen.ts is generated by TanStack Router and wires the root route from apps/…/__root.tsx to the file routes currently present in the tree. In this snapshot it registers / from apps/…/index.tsx and /editor from apps/web/src/routes/editor, then exposes typed route maps for full paths, route ids, and to destinations. The file also augments @tanstack/react-start with ssr: true and the app router type, which makes the routing tree part of the server-rendered TanStack Start contract. Because it is generated, changes should be made to route files and router/plugin configuration rather than edited directly.
apps/…/__root.tsx defines the document shell with createRootRoute. Its head() function owns the default document metadata and global links: UTF-8 charset, responsive viewport, title OpenCut rewrite | beta.opencut.app, /favicon.ico, Google Fonts preconnects, the Playfair Display stylesheet, and the bundled stylesheet URL imported from apps/web/src/styles.css?url. Its shellComponent renders the complete HTML document, injects HeadContent in <head>, wraps all route content in TooltipProvider, mounts TanStack devtools with a router devtools panel, and emits TanStack Start Scripts at the end of the body.
apps/…/index.tsx is the home route for /. It uses createFileRoute("/") and currently renders a minimal Home component with hello world!. This page is a child of the root document in the generated route tree, so it receives the global shell, tooltip context, styles, metadata, devtools, and scripts from apps/…/__root.tsx.
Global styling is centralized in apps/…/styles.css. It imports Tailwind CSS, tw-animate-css, shadcn Tailwind styles, and the Inter variable font package. The file defines a class-based dark variant with @custom-variant dark (&:is(.dark *)), maps Tailwind theme tokens to CSS variables in @theme inline, and declares light :root plus .dark values for background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, chart, radius, and sidebar tokens. Its base layer applies border and focus-outline defaults to all elements, sets the body background/text colors, sets the document font to Inter, applies the heading font token to headings, and keeps paragraph text on the foreground token.
Public app assets live under apps/web/public. apps/…/robots.txt allows all crawlers. apps/…/manifest.json still contains Create TanStack App sample metadata (TanStack App, Create TanStack App Sample), points its first icon at favicon.ico, also references logo192.png and logo512.png, starts at ., and declares standalone display with black theme color and white background. The root shell separately links /favicon.ico, which is present in the same public directory.
Build and deployment shape are split across the web package config files. apps/…/package.json defines the app package as private ESM @opencut/web; scripts run Vite dev on port 5173, Vite build, Vite preview, Vitest, and bun run build && wrangler deploy for deploy. Its dependencies include TanStack Router/Start/devtools, the Cloudflare and Tailwind Vite integrations, React 19, shadcn/UI-related packages, and the Inter font package used by apps/…/styles.css. apps/…/vite.config.ts enables tsconfig path resolution and installs Vite plugins in this order: TanStack devtools, Cloudflare with SSR environment name ssr, Tailwind CSS, TanStack Start, and React. apps/…/wrangler.jsonc deploys the app as Cloudflare Worker opencut-web using @tanstack/react-start/server-entry as main, nodejs_compat, compatibility date 2025-09-02, and custom domain route new.opencut.app. apps/…/moon.yml exposes Moon tasks that delegate to Bun scripts, with build inputs limited to src/**/*, public/**/*, vite.config.ts, tsconfig.json, and package.json, outputting dist; deploy depends on build.
TypeScript and UI generator settings round out the shell contract. apps/…/tsconfig.json compiles TS/TSX in bundler mode with strict checks, React JSX, DOM libraries, Vite client types, and aliases #/* and @/* to ./src/*. apps/…/package.json mirrors the #/* import alias for runtime/package import resolution. apps/…/components.json configures shadcn for non-RSC TSX components, points generated component styling at src/styles.css, uses CSS variables with neutral base color, chooses the Hugeicons icon library, and maps shadcn aliases such as components, ui, lib, and hooks to the #/* source alias. apps/…/.cta.json records the bootstrap choices for the TanStack app: file-router mode, TypeScript, React, Tailwind, Cloudflare, and shadcn.
Coupling
- If routes are added, removed, or renamed under
apps/web/src/routes, regenerate apps/…/routeTree.gen.ts and verify apps/…/router.tsx still imports the generated tree. The router factory depends on that generated file for both runtime route registration and TanStack Router type augmentation. - If the global stylesheet path or build handling changes, update apps/…/__root.tsx and apps/…/styles.css together. The root route links the stylesheet via
../styles.css?url; without that link the Tailwind/shadcn variables and base layer will not be included in the rendered document. - If aliases change in apps/…/tsconfig.json or apps/…/package.json, update apps/…/components.json aliases at the same time. shadcn generation targets
#/components,#/components/ui,#/lib, and#/hooks, so alias drift can generate imports that TypeScript or the bundler cannot resolve. - If deployment moves away from TanStack Start SSR, check both apps/…/vite.config.ts and apps/…/wrangler.jsonc. The Vite config installs
tanstackStart()and the Cloudflare SSR environment, while Wrangler pointsmainat@tanstack/react-start/server-entry; these need to agree on the server entry shape. - If public branding changes, update apps/…/__root.tsx, apps/…/manifest.json, and
apps/web/public/favicon.icotogether. The HTML title/favicon are owned by the root route, while install/PWA metadata is owned by the manifest and currently still uses sample TanStack names and missing logo references. - If Moon task caching should include deployment/runtime config, add the relevant files to apps/…/moon.yml. The current build inputs include source, public assets, Vite config, TypeScript config, and package metadata, but not wrangler.jsonc, components.json, or .cta.json.
Risks
- apps/…/routeTree.gen.ts is generated but checked in. Editing it directly can be overwritten by TanStack Router generation, and failing to regenerate it after route-file changes can leave apps/…/router.tsx serving stale route registrations or stale route types.
- apps/…/manifest.json references logo192.png and logo512.png, but the public directory coverage only contains
favicon.ico, manifest.json, and robots.txt. If the manifest is consumed by browsers or install flows, those icon URLs can 404 until matching files are added or the manifest is corrected. - apps/…/moon.yml does not list wrangler.jsonc as a build input. If Cloudflare deployment configuration changes without source or package changes, Moon may not consider the web build task affected even though the deploy target or Worker runtime contract changed.