Next.js App Router Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Next.js App Router structure within the cyoa-engine application serves as the primary user-facing interface for the MCP Games ecosystem. It provides a React-based frontend that facilitates interactive narrative experiences by connecting users to various Model Context Protocol (MCP) servers such as GitHub, Linear, and Notion.
This module utilizes Next.js 14 features, including Server Components by default, to manage the application's layout, global styling, and main entry point. It is integrated within a Turborepo monorepo, allowing it to leverage shared logic from internal packages like shared-types, mcp-sdk, and story-engine.
Sources: apps/cyoa-engine/README.md:1-15, apps/cyoa-engine/package.json:1-20
Core Framework Configuration
The application is built on Next.js 14, utilizing the app/ directory for routing. The configuration ensures that the frontend can interact with internal monorepo packages through package transpilation.
Build and Runtime Configuration
The next.config.js file defines the environment and build-time behavior, specifically enabling reactStrictMode and ensuring that internal workspace packages are correctly transpiled for the browser environment.
/** @type {import('next').NextConfig} */
const nextConfig = {
reactStrictMode: true,
transpilePackages: ['shared-types', 'mcp-sdk', 'story-engine'],
env: {
MCP_CONNECTOR_URL: process.env.MCP_CONNECTOR_URL || 'http://localhost:3001',
NARRATIVE_AI_URL: process.env.NARRATIVE_AI_URL || 'http://localhost:8000',
},
}
Sources: apps/cyoa-engine/next.config.js:2-10
Dependency Management
The application depends on modern React and Next.js libraries, supplemented by specialized state management and data fetching tools.
| Dependency | Purpose |
|---|---|
next | Core framework (v14.0.4) |
react | UI Library |
zustand | Client-side state management |
@tanstack/react-query | Data fetching and caching |
shared-types | Workspace package for type safety |
story-engine | Workspace package for game logic |
Sources: apps/cyoa-engine/package.json:14-25, apps/cyoa-engine/README.md:20-25
Routing and Layout Architecture
The cyoa-engine uses a hierarchical structure to define the global UI shell and specific page content.
Root Layout
The RootLayout component in app/layout.tsx defines the high-level HTML structure, including the language attribute and font injection. It serves as a wrapper for all pages in the application.
The layout manages the application's metadata, setting the title to "MCP Games - CYOA Engine" and applying the Inter font subset to the body.
Sources: apps/cyoa-engine/app/layout.tsx:5-24
Main Application Page
The Home component in app/page.tsx represents the default route (/). It provides the primary dashboard where users can start adventures or configure MCP connections.
Key UI Sections:
- Narrative Intro: Welcomes the user to the personalized story experience.
- Feature Grid: Displays cards for MCP Integration, AI Narratives, and Personalized Choices.
- Action Buttons: Triggers for "Start Adventure" and "Configure MCPs".
Sources: apps/cyoa-engine/app/page.tsx:1-50
Data Flow and Integration
The App Router structure is designed to interface with external services through environment variables and shared SDKs.
Service Integration Flow
The frontend communicates with the mcp-connector for data retrieval and the narrative-ai service for story generation.
The application uses MCP_CONNECTOR_URL and NARRATIVE_AI_URL to route requests to the appropriate backend services within the monorepo.
Sources: apps/cyoa-engine/next.config.js:6-9, apps/cyoa-engine/README.md:28-33
Project Styling and Typescript Configuration
The project utilizes Tailwind CSS for styling and a shared TypeScript configuration to ensure consistency across the monorepo.
- TypeScript: Extends
../../tsconfig.base.jsonand configures path aliases (e.g.,@/*for./src/*). It specifically includes Next.js types for the App Router. - Styling: PostCSS and Tailwind CSS are used, with configurations extending to the
appandcomponentsdirectories.
Sources: apps/cyoa-engine/tsconfig.json:2-25, apps/cyoa-engine/tailwind.config.ts:3-15
Summary
The Next.js App Router Structure in cyoa-engine provides a centralized frontend for the MCP Games ecosystem. By utilizing Next.js 14 layouts and pages, it creates a structured environment for narrative generation and MCP management. The architecture relies on workspace transpilation to integrate core logic from story-engine and mcp-sdk, ensuring type-safe interactions between the UI and the underlying game state.