> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-019: Defer Next.js / Turbopack for the authenticated ERP shell

> Status: Accepted Date: 2026-04-24 Participants: Platform Architecture, Jeremy Bloom (product owner)

**Status:** Accepted\
**Date:** 2026-04-24\
**Participants:** Platform Architecture, Jeremy Bloom (product owner)

***

## Context

Turbopack is the default bundler for Next.js 16+ and excels at App Router / RSC development workflows. **Turborepo** (monorepo task runner) is already adopted in this repository and must not be confused with Turbopack.

The platform frontend is a **Vite + React Router SPA** by explicit decision in [ADR-008](./ADR-008-vite-spa-vs-ssr.md): authenticated ERP, no SEO requirement, Supabase client auth without SSR cookie complexity, PWA via Workbox.

Occasional questions arise: “Should we move the main app to Next.js for Turbopack / RSC performance?”

## Decision

**Defer** migrating the authenticated Encore Health OS shell to Next.js solely to adopt Turbopack or RSC.

Continue to invest in:

* Vite / Rolldown production configuration and chunking (`vite.config.ts`)
* Route-level `React.lazy` and heavy vendor dynamic imports (existing patterns)
* Turborepo remote cache + CI cache for developer iteration (see `docs/development/TURBOREPO_USAGE.md`)
* Narrow, measurement-driven **Vercel Microfrontends** splits (see `docs/development/MICROFRONTENDS_RUNBOOK.md`) — not a per-core microfrontend explosion

## Rationale

1. **ADR-008 still applies** — SSR/RSC benefits are marginal for an all-authenticated ERP; cost is large (auth model, PWA, deployment, testing surface).
2. **Turbopack does not replace Vite** in the current stack without a framework migration; conflating “Turbo repo” and “Turbopack” creates planning errors.
3. **Performance wins** are gated first on bundle discipline, caching, and runtime metrics — not bundler brand.

## Triggers to revisit (requires a new ADR)

Re-open a migration or add a **separate** Next.js surface only if **product** requirements justify it, for example:

* A marketing or public content property needs SEO/SSR at the same domain as the app, **and** the team accepts operating two shells.
* Regulatory or integration mandates require server-rendered clinical or billing surfaces that cannot be met by the SPA + edge functions model.
* Vite/Rolldown ceases to meet build or dev performance needs **after** documented optimization attempts (`docs/development/PERFORMANCE_BASELINE.md`).

## Consequences

### Positive

* Single mental model for the main product (SPA + Supabase + PWA).
* No forced server/client component split across 7k+ source files.
* Planning energy stays on measurable user-perceived performance and CI time.

### Negative

* We do not get Next-specific ergonomics (e.g. built-in image/font conventions) on the main shell; mitigations remain Vite ecosystem plugins and platform patterns.

## Related documents

* [ADR-008](./ADR-008-vite-spa-vs-ssr.md)
* [ADR-017](./ADR-017-microfrontends-pwa-scoping.md)
* `docs/development/PERFORMANCE_BASELINE.md`
* `docs/development/TURBOREPO_USAGE.md`
* `docs/development/MICROFRONTENDS_RUNBOOK.md`