Installing Flowpane for Next.js

You need permission to manage the Site in Flowpane, access to the Next.js project, and access to its hosting environment settings and deployment process. Check Compatibility first.

Run the commands below in the folder that contains the application's package.json.

1. Add the package

In Flowpane, open the Site, then Settings → Integrations → Next.js integration, and choose Download package. The page shows the package's SHA-256 checksum, which you can compare with the downloaded file. Then install the downloaded file:

npm install /path/to/flowpane-next.tgz

Install the package only from your Flowpane Integrations page, not from another source.

2. Wrap the Next.js configuration

Open your existing next.config.mjs or next.config.ts, add the import and wrap the exported configuration. Keep your existing settings.

import { withFlowpane } from '@flowpane/next/config'

const nextConfig = {}

export default withFlowpane(nextConfig)

A function or async configuration is accepted too. A CommonJS next.config.js must first be converted to next.config.mjs.

3. Add the Flowpane route

App Router: create app/api/flowpane/route.ts. If your application uses src/app/, create src/app/api/flowpane/route.ts and import ../../../../flowpane-source.json instead.

import { createFlowpaneHandler } from '@flowpane/next'
import source from '../../../flowpane-source.json'

export const runtime = 'nodejs'
export const GET = createFlowpaneHandler({ source })

Pages Router: create pages/api/flowpane.ts. If your application uses src/pages/, create src/pages/api/flowpane.ts and import ../../../flowpane-source.json instead.

import { createFlowpanePagesHandler } from '@flowpane/next'
import source from '../../flowpane-source.json'

export default createFlowpanePagesHandler({ source })

The configuration wrapper creates flowpane-source.json during each build. Do not edit or commit it. If your editor reports it missing before the first build, run npm run build once.

4. Create the private identity

Run:

npx flowpane-next identity

This creates .flowpane/identity.env and adds the private folder and the generated file to .gitignore; it never prints the secret. Add its FLOWPANE_NEXT_IDENTITY value to your host's server-only environment settings. Never use a NEXT_PUBLIC_ prefix, put it in next.config, or commit .flowpane/. Keep the identity for later deployments.

The value is longer than some hosting control panels accept for one environment variable (some stop at 255 characters). If your host cannot store it, add the whole line to a server-only .env.production file in the application folder instead. Next.js reads that file when the server starts. Keep the file out of public/ and any other folder your web server serves directly, and never commit it.

5. Build and deploy

Build and deploy through your usual process. The Flowpane route must be reachable at /api/flowpane on your exact HTTPS Site address, without a login, redirect or CDN cache. Then connect the Site.