Frontend App Overview (`apps/web`)
Relevant source files
The following files were used as context for generating this wiki page:
The apps/web application is the primary frontend interface for the contract-based-monorepo project. It is a modern web application built with React 19 and the TanStack ecosystem, including TanStack Router for type-safe routing and TanStack Query for asynchronous state management. The application is designed to be a consumer of the Hono API server, leveraging shared contracts for type safety.
Styling is managed through a utility-first approach with Tailwind CSS, complemented by unstyled, accessible UI components from Radix UI, which are integrated via shadcn/ui. The build system is powered by Vinxi and Vite, providing a fast development experience and an optimized production build.
Sources: README.md:12-21, apps/web/package.json:12-40, apps/web/README.md:1-4
Core Architecture and Dependencies
The apps/web package is a crucial part of the monorepo, interacting with other local packages like @contract-based-monorepo/ui for shared components.
Sources: apps/web/package.json:12
Dependency Graph
The following diagram illustrates the key dependencies of the apps/web application within the monorepo and its core external libraries.
Sources: apps/web/package.json:12-40, README.md:12-21
Key Dependencies
The functionality of the apps/web application is supported by several key libraries.
| Dependency | Version | Description |
|---|---|---|
@contract-based-monorepo/ui | workspace:* | Shared UI component library from within the monorepo. |
react | ^19.0.0 | A JavaScript library for building user interfaces. |
@tanstack/react-router | ^1.114.3 | Type-safe, file-based routing for React. |
@tanstack/react-query | ^5.66.5 | Asynchronous state management and data fetching. |
vinxi | ^0.5.3 | The build tool and development server used for the application. |
tailwindcss | ^4.0.8 | A utility-first CSS framework for styling. |
@radix-ui/react-slot | ^1.2.0 | Core component for composing shadcn/ui components. |
zod | ^3.24.2 | TypeScript-first schema declaration and validation. |
Sources: apps/web/package.json:12-40
Routing
Routing is managed by TanStack Router using a file-based system. Routes are defined by creating files within the src/routes directory. This structure is automatically processed to generate a type-safe route tree.
Sources: apps/web/README.md:28-31, apps/web/src/routeTree.gen.ts
Root Layout
The main layout for the entire application is defined in src/routes/__root.tsx. This file establishes the root HTML document structure, includes global stylesheets, and defines components that persist across all pages, such as the <Header />. The <Outlet /> component is used to render the content of the currently active child route.
The root route is also responsible for providing context to its children, such as the QueryClient instance for TanStack Query.
Sources: apps/web/src/routes/__root.tsx:1-58, apps/web/README.md:46-62
// File: apps/web/src/routes/__root.tsx
// ...
export const Route = createRootRouteWithContext<MyRouterContext>()({
// ...
component: () => (
<RootDocument>
<Header />
<Outlet />
<TanStackRouterDevtools />
<TanstackQueryLayout />
</RootDocument>
),
});
// ...
Sources: apps/web/src/routes/__root.tsx:21-36
Route Generation Flow
The file-based routing system follows a clear flow from file creation to a navigable application route.
The generated route tree file, src/routeTree.gen.ts, contains the structured route definitions and type information derived from the files in src/routes.
Sources: apps/web/src/routeTree.gen.ts
Example Route: Index
The home page of the application is defined in src/routes/index.tsx. It uses the createFileRoute function to associate the component with the / path. This component is then rendered inside the <Outlet /> of the root layout.
// File: apps/web/src/routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";
// ...
export const Route = createFileRoute("/")({
component: App,
});
function App() {
// ... component JSX
}
Sources: apps/web/src/routes/index.tsx:2-8
State Management and Data Fetching
The application uses TanStack Query for managing server state and data fetching. The QueryClient is instantiated and provided to the application through the root route's context. A TanstackQueryLayout component is included in the root layout, likely to house the QueryClientProvider.
Sources: apps/web/src/routes/__root.tsx:12,18,34, apps/web/README.md:83-93
Styling and UI Components
The apps/web application uses Tailwind CSS for styling, configured with a zinc base color and CSS variables for theming. It also leverages shadcn/ui for its component library, which is configured in apps/web/components.json.
Sources: apps/web/components.json:3-11, apps/web/src/styles.css
The configuration specifies path aliases for easy importing of components and utilities.
| Alias | Path |
|---|---|
components | @/components |
utils | @/lib/utils |
ui | @/components/ui |
Sources: apps/web/components.json:12-17
The application imports its primary styles from src/styles.css, which in turn imports Tailwind CSS and defines custom properties for light and dark themes.
Sources: apps/web/src/routes/__root.tsx:14, apps/web/src/styles.css:1-3
Build and Configuration
The application is built using Vinxi and configured via apps/web/app.config.ts. This configuration integrates Vite plugins, notably @tailwindcss/vite for Tailwind CSS processing and vite-tsconfig-paths to enable TypeScript path aliases (e.g., @/components) during development and build.
// File: apps/web/app.config.ts
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "@tanstack/react-start/config";
import viteTsConfigPaths from "vite-tsconfig-paths";
export default defineConfig({
// ...
vite: {
plugins: [
// this is the plugin that enables path aliases
viteTsConfigPaths({
projects: ["./tsconfig.json"],
}),
tailwindcss(),
],
},
});
Sources: apps/web/app.config.ts:1-17
The package.json file defines the scripts for running, building, and testing the application.
pnpm dev: Starts the development server with Vinxi.pnpm build: Creates a production build of the application.pnpm type:check: Runs the TypeScript compiler to check for type errors.
Sources: apps/web/package.json:5-10