Nuxt

Nuxt powers the main authenticated web workspace, the token replacer shell, and the shared auth layer used by both web-user apps.

Keep nuxt and @nuxt/ui aligned across all three Nuxt consumers:

apps/web
apps/web-token-replacer
packages/nuxt-auth-layer

What It Owns

apps/web owns the user-facing workspace UI, connectors, chat, Library, Skills, and Response Templates.
apps/web-token-replacer owns the authenticated TODO shell for the future token replacer product.
packages/nuxt-auth-layer owns shared auth-facing pages, route middleware, session store, auth composables, auth-specific components, and auth BFF routes.
Nuxt provides file-based routing, SSR/hybrid rendering, auto-imports, Nitro server routes, app middleware, and the Vue runtime boundary.
Nuxt UI and the shared web design system sit on top of this app framework.

Architecture Decision

Decision: use Nuxt for web-user apps so the product can combine Vue UI ergonomics, server-aware routes, auth middleware, and deployable full-stack behavior. Shared Nuxt auth behavior lives in a Nuxt layer rather than duplicated app-local code.

The web app should stay thin around product contracts: operational copy belongs in the frontend, shared DTOs come from repo contracts, and auth/runtime decisions stay in the owning services.

How To Upgrade

Use Nuxt’s official upgrade command from the web workspace:

bun x nuxt upgrade

Then run:

bun run --cwd apps/web prepare:types
bun run --cwd apps/web check-types
bun run --cwd apps/web test
bun run --cwd packages/nuxt-auth-layer test
bun run --cwd apps/web-token-replacer test

Run the Nuxt prepare/type/test commands sequentially when they touch packages/nuxt-auth-layer. The layer writes generated .nuxt files, and concurrent prepares can race while removing or writing those generated directories.

Run bun run --cwd apps/web test:e2e when main web routing, auth, connectors, chat, or layout behavior could change. Run bun run --cwd apps/web-token-replacer test:e2e when shared auth redirects or token replacer shell behavior could change.

Nuxt 5 is still marked as in development in the official Nuxt 4 upgrade docs. Do not opt into Nuxt 5 compatibility behavior as part of a routine Nuxt 4 upgrade unless that scope is explicitly accepted.

Current Limits

Do not add backend-authored English operational copy to web-facing service contracts. Use status/error/detail codes plus web-owned copy.
Before adding new UI primitives, check existing Nuxt UI components and local web base components first.
For visible UI behavior, use browser verification when it can catch layout, state, or interaction regressions.

Canonical Sources

packages/nuxt-auth-layer/
apps/web/
apps/web-token-replacer/
apps/web/package.json
apps/web-token-replacer/package.json
apps/web/AGENTS.md
DESIGN.md
docs/features/authentication/spec.md
docs/features/chat/spec.md
docs/features/connectors/spec.md