Kartuli Docs

Appearance

Next.js ​

Role and consumers ​

Game Client and Backoffice are Next.js 16 applications. Game Client's App Router entrypoints are under src/app/[locale]; Backoffice currently has an /en scaffold. App-specific routes and intended behavior belong to Apps, not a shared framework tutorial.

Server and client boundaries ​

Route components compose the app's feature UI. Game Client learning content is built from bundled JSON through ingestion/library modules and supplied through server-side code. Browser identifiers, IndexedDB and reactive state belong on the client side. The root query provider uses a lazy React state initializer so its QueryClient survives re-renders.

Keep browser APIs out of server execution; use client boundaries where state/effects/browser access require them. A TypeScript alias does not make a server module safe to import into browser code. Inspect imported modules when moving logic across that boundary.

Configuration ​

Game Client next.config.ts sets the Turbopack root to the monorepo, exposes NEXT_PUBLIC_APP_VERSION with its package version as fallback, disables the experimental development filesystem cache and wraps config with withSerwist. It also enables Next.js's experimental globalNotFound entry because the Game Client starts with a dynamic [locale] root layout: unmatched URLs need a router-level 404 before rendering begins, while the global entry supplies its own complete document. The monorepo root is necessary because source packages live outside the app directory. The cache override applies to the development compiler, not Turbo's task cache. The Serwist wrapper does not establish complete offline operation; see Serwist.

Backoffice exposes the same version variable and defines a temporary redirect from / to /en; it does not configure the Game Client Turbopack root or Serwist. Review each app config independently rather than assuming parity.

Game Client src/proxy.ts handles locale redirects and forwards the trusted locale/path headers used by the global not-found entry. Its literal matcher includes application routes and excludes Next internals and known public assets. When adding a root asset, review the matcher; when adding a locale, review the supported-locale resources and routing tests. Shared TypeScript config provides bundler resolution; app configs add the Next plugin and generated types.

Development and verification ​

bash
pnpm run c:dev:game-client
pnpm run c:build:game-client
pnpm run c:preview:game-client

Game Client development/start/preview uses port 3000. Backoffice development/start/preview uses port 3001, allowing both local apps to run side-by-side. Preview builds then starts the production server. Building is distinct from lint/typecheck/unit tests; Next font downloads can introduce a network prerequisite.

Before changing Next.js implementation, AGENTS.md requires reading the installed docs under apps/game-client/node_modules/next/dist/docs. For framework upgrades, inspect those docs, catalog/lockfile, Serwist compatibility, type generation, routing tests and production build output. Check both apps and Storybook's imports of app components. Deployment provider specifics belong to Vercel.