@fluxfast/next

Next.js App Router adapter for FluxFast. FastAPI owns application routing, validation, authentication, and data loading; Next.js supplies the document, bundling, React runtime, and code splitting.

npm install @fluxfast/next

Wrap the Next config to generate the component allowlist and proxy only FluxFast protocol requests to the private FastAPI address:

import { withFluxFast } from "@fluxfast/next/next-config";

export default withFluxFast({
  reactStrictMode: true,
});

fluxfast init also creates a reserved server-only route for /fluxfast/healthz and /fluxfast/readyz. These checks proxy the private FastAPI runtime through the public Next.js origin without exposing its address.

Page paths may use ASCII letters, digits, _, ., @, parentheses, brackets, and hyphens, with / between directories and a .tsx or .jsx extension. The generator rejects other characters before emitting import paths.

Create the optional catch-all shell at app/(flux)/[[...flux]]/page.tsx:

import { createFluxNextPage } from "@fluxfast/next/server";
import { fluxConfig } from "@/fluxfast.config";

export default createFluxNextPage(fluxConfig);

During development, run the supervisor from the consuming application:

.venv/bin/fluxfast dev backend.app.main:app

The supervisor starts FastAPI on a private available port and Next.js on the browser-facing port. Browser transport stays same-origin, so no public backend port or development CORS configuration is required. The supervisor detects npm, pnpm, Yarn, or Bun from the consuming frontend.

Contract & Validator Generation

When the FastAPI application defines typed resources, general contracts, or JSON mutations, generate frontend artifacts with the Next.js CLI:

npx fluxfast generate
# or use the full-stack helper from Python:
fluxfast types backend.app.main:app --frontend frontend

This compiles:

• types.generated.ts: TypeScript contracts for resources, general application models, and reusable mutation request bodies.
• validators.generated.ts: Tree-shakeable native runtime validators powered by @fluxfast/core with zero third-party dependencies.
• routes.generated.ts: Safely encoded, typed FastAPI page URL builders.
• mutations.generated.ts: Typed mutation helpers consuming reusable body contracts.
• pages.generated.ts: Component registry allowlisting discovered page components.

Pass generated validators to useForm for instant client-side validation and zero-network invalid submissions:

import { useForm } from "@fluxfast/next";
import { CreateUserInputValidator } from "@/.fluxfast/validators.generated";

const form = useForm(initialData, { validator: CreateUserInputValidator });

The package supports Next.js >=16.3.0 <17.0.0, React 19, and Node.js 22 and 24. See the complete Next.js adapter guide, general application contracts, native client validation, caching guide, and mutation guide.

FluxFast is licensed under the MIT License.