# Next.js App Router Structure in NextChat: A Comprehensive Technical Guide > Explore the Next.js App Router structure in NextChat using file-system routing and edge runtime API handlers. Learn its dual-configuration pattern for server-side secrets and client-side feature flags. - Repository: [NextChat/NextChat](https://github.com/ChatGPTNextWeb/NextChat) - Tags: deep-dive - Published: 2026-02-28 --- **NextChat leverages Next.js 13+ App Router with file-system based routing, edge-runtime API handlers, and a dual-configuration pattern that keeps API secrets server-side while exposing safe feature flags to the browser via HTML meta tags.** NextChat (ChatGPTNextWeb/NextChat) is built on Next.js 13+ and utilizes the modern App Router architecture (`app/` directory) instead of the legacy Pages Router. The codebase implements a sophisticated routing structure that combines React Server Components, edge runtime API proxies, and dynamic catch-all segments to efficiently proxy requests to multiple LLM providers like OpenAI, Azure, Google, and Anthropic. ## Root Layout as the Global HTML Wrapper The [`app/layout.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/layout.tsx) file serves as the top-level layout that wraps every page in the application. It defines the global HTML structure, injects server-side configuration into the document head, and conditionally renders analytics scripts based on environment variables. ```tsx // app/layout.tsx export const metadata: Metadata = { … }; export const viewport: Viewport = { … }; export default function RootLayout({ children }: { children: React.ReactNode }) { const serverConfig = getServerSideConfig(); return ( {children} {serverConfig?.isVercel && } {serverConfig?.gtmId && } {serverConfig?.gaId && } ); } ``` Key responsibilities of the root layout include: - **Global styles**: Imports [`globals.scss`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/globals.scss), [`markdown.scss`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/markdown.scss), and [`highlight.scss`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/highlight.scss) at the top of the file. - **Server-side configuration**: Calls `getServerSideConfig()` from [`app/config/server.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/server.ts) to access environment variables and feature flags. - **Client-side config injection**: Embeds a sanitized configuration object via `` using `getClientConfig()` from [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts). - **Conditional analytics**: Renders `GoogleTagManager` and `GoogleAnalytics` components only when `gtmId` or `gaId` are present in the server config. ## Home Page as the Default Route The [`app/page.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/page.tsx) file represents the root route (`/`) and acts as the entry point for the chat interface. Because this file exists directly under the `app/` directory, Next.js automatically maps it to the root URL path without requiring explicit routing configuration. ```tsx // app/page.tsx export default async function App() { const serverConfig = getServerSideConfig(); return ( <> {serverConfig?.isVercel && } ); } ``` This server component fetches configuration at request time and renders the main `Home` UI component. The use of an `async` function allows for server-side data fetching before hydration, though the component primarily relies on client-side state management for the chat interface. ## Dynamic API Routes with Edge Runtime NextChat implements a generic proxy system for LLM APIs using dynamic route segments. The architecture relies on the catch-all pattern `[...path]` combined with the dynamic `[provider]` segment to route requests to various AI providers through a single interface. ### The Catch-All Provider Pattern The `app/api/[provider]/[...path]/route.ts` file handles requests for all supported LLM providers: ```tsx // app/api/[provider]/[...path]/route.ts export const GET = handle; export const POST = handle; export const runtime = "edge"; async function handle(req: NextRequest, { params }: { params: { provider: string; path: string[] } }) { const { provider } = params; // Routes to specific provider implementations based on the ApiPath constant } ``` This edge runtime handler inspects `params.provider` and forwards requests to specific provider modules such as OpenAI, Azure, Google, or Anthropic. The `export const runtime = "edge"` declaration ensures these handlers execute on Vercel Edge Functions for minimal latency. ### Provider-Specific Edge Handlers Individual provider routes follow the same edge runtime pattern. For example, the Tencent implementation in [`app/api/tencent/route.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/api/tencent/route.ts) demonstrates authentication handling: ```tsx // app/api/tencent/route.ts export const GET = handle; export const POST = handle; export const runtime = "edge"; ``` These handlers implement provider-specific logic including: - **AbortController**: Enforces a 10-minute timeout on streaming requests. - **Dynamic base URLs**: Retrieves endpoints from `serverConfig.tencentUrl` with fallback to environment variables. - **Signature headers**: Generates HMAC authentication using utilities from [`app/utils/tencent.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/tencent.ts). Additional utility modules supporting the router include: - [`app/utils/format.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/utils/format.ts): Error pretty-printing via `prettyObject`. - [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts): Central `ApiPath` enum and provider constants. ## Configuration Architecture: Server vs. Client NextChat implements a strict separation between server-only secrets and client-safe configuration to prevent API key leakage while maintaining feature flag availability in the browser. ### Server-Side Configuration The [`app/config/server.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/server.ts) file exports `getServerSideConfig()`, the single source of truth for all environment-driven settings: ```tsx // app/config/server.ts export const getServerSideConfig = () => { return { baseUrl: process.env.BASE_URL, apiKey: getApiKey(process.env.OPENAI_API_KEY), isAzure: !!process.env.AZURE_URL, azureUrl: process.env.AZURE_URL, gtmId: process.env.GTM_ID, gaId: process.env.GA_ID || DEFAULT_GA_ID, // Provider-specific flags and feature toggles }; }; ``` All API routes and server components import this function to access secrets and runtime flags consistently. ### Client-Side Configuration The [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts) file reads the serialized configuration injected by the root layout's meta tag: ```tsx // app/config/client.ts export function getClientConfig() { if (typeof document !== "undefined") { return JSON.parse(queryMeta("config") || "{}") as BuildConfig; } return getBuildConfig(); // fallback for SSR } ``` This pattern ensures sensitive values like `OPENAI_API_KEY` remain server-side only, while necessary UI flags (such as `hideUserApiKey` or `disableGPT4`) are safely exposed to the client. ## Extending the Router with New Providers To add a new LLM provider called "FooAI" to the NextChat App Router: 1. **Create the route file** at [`app/api/fooai/route.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/api/fooai/route.ts) exporting `GET`, `POST`, and `runtime = "edge"`. 2. **Implement the handler** function with provider-specific authentication and request forwarding logic. 3. **Register the constant** in [`app/constant.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/constant.ts) (e.g., `ApiPath.FooAI = "/api/fooai"`). 4. **Update the catch-all router** in `app/api/[provider]/[...path]/route.ts` to import and route to the new handler: ```tsx import { handle as fooaiHandler } from "../../fooai"; case ApiPath.FooAI: return fooaiHandler(req, { params }); ``` 5. **Add environment variables** to [`app/config/server.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/server.ts) (e.g., `FOOAI_API_KEY`). The App Router automatically recognizes the new file-system structure without additional routing configuration. ## Summary - **File-system routing**: The `app/` directory structure directly defines available routes, with [`page.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/page.tsx) files serving as route entry points and [`layout.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/layout.tsx) providing shared wrappers. - **Edge runtime deployment**: API routes use `export const runtime = "edge"` to execute on Vercel Edge Functions, ensuring low-latency LLM API proxying. - **Dynamic catch-all segments**: The `[provider]/[...path]` pattern enables a unified proxy interface for multiple AI providers through a single route handler. - **Configuration split**: `getServerSideConfig()` manages secrets server-side, while `getClientConfig()` safely exposes feature flags via HTML meta tags injected in [`app/layout.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/layout.tsx). ## Frequently Asked Questions ### How does NextChat handle multiple LLM providers in the App Router? NextChat uses a dynamic catch-all route at `app/api/[provider]/[...path]/route.ts` that captures the provider name and remaining URL segments. The handler inspects `params.provider` against the `ApiPath` enum and routes requests to provider-specific handlers (OpenAI, Azure, Anthropic, etc.) imported from sibling directories like `app/api/openai/` or `app/api/tencent/`. ### What prevents API keys from leaking to the browser in NextChat? The codebase maintains a strict separation where `getServerSideConfig()` in [`app/config/server.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/server.ts) accesses raw environment variables only on the server. The root layout injects a sanitized subset of this configuration via a `` tag, which `getClientConfig()` in [`app/config/client.ts`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/config/client.ts) reads at runtime. Sensitive values like `OPENAI_API_KEY` are never serialized into this meta tag. ### Can I use the standard Next.js Link component for navigation in NextChat? Yes. Client components within NextChat use the standard Next.js `Link` component from `next/link` for client-side navigation. However, most of the application state lives in global stores and URL hashes rather than distinct routes, as the chat interface primarily operates as a single-page application within the root layout. ### How do I add environment-specific analytics to NextChat? Analytics scripts like Google Tag Manager and Google Analytics are conditionally rendered in [`app/layout.tsx`](https://github.com/ChatGPTNextWeb/NextChat/blob/main/app/layout.tsx) based on the `gtmId` and `gaId` values returned by `getServerSideConfig()`. To enable tracking, set the `GTM_ID` or `GA_ID` environment variables; the components only mount when these config values exist, ensuring clean builds without analytics in development environments.