ADR-0006: Next.js 16 proxy.ts Migration

Status

Accepted

Date: 2026-03-05

Context

Next.js 16 deprecated middleware.ts in favor of proxy.ts to better reflect the file’s actual purpose as a network boundary/proxy layer. The middleware naming was misleading since the file operates as a reverse proxy intercepting requests before they reach the application, not as traditional middleware in the Express/Koa sense.

All 8 monorepo apps used middleware.ts for:

• i18n routing: Locale detection and path rewriting via next-intl’s createMiddleware
• Auth protection: Route guards via Convex Auth middleware wrapper
• Request manipulation: Header injection, redirects, and rewrites

Key constraints:

• All apps needed to migrate simultaneously to avoid inconsistency
• The proxy file moved from project root to src/proxy.ts
• Runtime changed from Edge to Node.js

Decision

Migrated all apps from middleware.ts to src/proxy.ts. The proxy handles:

1. i18n locale detection via next-intl’s createMiddleware (unchanged API, new file location)
2. Auth protection via Convex Auth middleware wrapper (unchanged API)
3. Path matching via the config.matcher export (unchanged pattern)

The migration was a file rename and path change with no functional changes to the proxy logic itself.

Consequences

Positive

• Aligns with Next.js 16 conventions and official documentation
• Clearer naming that accurately describes the file’s purpose as a network proxy layer
• Runs on Node.js runtime instead of Edge, enabling access to Node.js APIs and larger dependency trees
• Consistent with the broader Next.js ecosystem direction

Negative

• Required touching all 8 apps in a single coordinated change
• Documentation and onboarding materials needed updating
• Third-party tutorials and Stack Overflow answers still reference middleware.ts

Neutral

• No functional changes to routing or auth logic
• next-intl and Convex Auth both support the new file location without API changes
• The config.matcher export pattern remains identical

Alternatives Considered

Alternative 1: Keep middleware.ts

• Description: Continue using the deprecated middleware.ts file location
• Pros: No migration effort, existing docs still valid
• Cons: Deprecated, will likely be removed in future Next.js versions, confusing for new developers reading current docs
• Why not chosen: Accumulating technical debt on a clear deprecation path

Alternative 2: Use API Routes for Routing Logic

• Description: Move i18n and auth logic to API route handlers
• Pros: More explicit control, no special file conventions
• Cons: Loses the automatic interception of all requests, significant refactor, worse performance
• Why not chosen: Over-engineered solution for a straightforward file rename

References

• Next.js 16 Migration Guide
• next-intl middleware documentation
• Related: ADR-0001 (Monorepo Structure)

Notes

• The proxy.ts file must be in src/ when using the src/ directory convention
• Apps without i18n (e.g., portfolio) have minimal proxy files that only handle basic redirects
• Future Next.js versions may expand the proxy API with additional capabilities