Skip to main content

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.

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: 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.
  • ADR-008
  • ADR-017
  • docs/development/PERFORMANCE_BASELINE.md
  • docs/development/TURBOREPO_USAGE.md
  • docs/development/MICROFRONTENDS_RUNBOOK.md