Next.js

Set up a Next.js app for a Revyl Web session. Revyl does not infer the Next.js framework or package manager from revyl init; author the Web recipe from your app's existing scripts and lockfile.

Set up with an agent

Paste one prompt and your coding agent does the rest.

Copy setup promptPreview prompt

Setup prompt

Copy

Set up Revyl for this Next.js app.

Read https://docs.revyl.com/frameworks/nextjs.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

Web is in Alpha: if Revyl says Web isn't enabled for my organization, stop and tell me to email support@revyl.ai. If the app already deploys previews, register its HTTPS preview. Otherwise use its package manager and standalone output to package a self-contained server with Linux x86-64-compatible dependencies.

You're done when a Revyl Web session opens the Next.js app and you've given me its link.

Ask me before anything that needs my login or approval.

Build guidanceCopy Anchor Link

A managed Next.js bundle runs its standalone server inside the Web session. Rebuild after a code change and open the new build in a new session. Revyl does not provide Web hot reload. If the app already deploys previews, register its HTTPS preview instead of packaging it as a managed bundle.

PrerequisitesCopy Anchor Link

• A Next.js app with a working production build.
• The package manager and lockfile already used by the app.
• Revyl CLI installed and authenticated with revyl auth login.
• Web enabled for your organization.

Configure a managed bundleCopy Anchor Link

First create the Web app and project profile. Enable standalone output in the app's existing Next config, keeping its other settings:

module.exports = {
  output: "standalone",
};

Add a recipe that packages the standalone server, static assets, and public files when present:

build:
  profiles:
    preview:
      web:
        app_id: <web-app-id>
        setup_commands: [npm ci]
        build_commands:
          - npm run build
          - rm -rf dist-revyl && mkdir -p dist-revyl/.next
          - cp -RL .next/standalone/. dist-revyl/
          - cp -R .next/static dist-revyl/.next/static
          - if [ ! -d public ]; then exit 0; fi; cp -R public dist-revyl/public
        output_path: dist-revyl
        run:
          start: HOSTNAME=0.0.0.0 node server.js
          port: 3000

Use the package manager and lockfile that the app already uses instead of copying npm ci blindly. The example assumes .next/standalone/server.js is the entrypoint; in a monorepo, adjust the copied assets and run.start to the standalone output's layout.

The server must listen on 0.0.0.0 at the configured port. The output directory must contain the standalone server, .next/static, public when present, and the server's runtime dependencies. Remote Web recipes build on Linux ARM64; bundled servers run on Linux x86-64. Native Node dependencies must include binaries for the session runtime, not just the build machine. Use a hosted preview if you cannot package compatible dependencies. See Web builds for the full bundle limits.

Optional test-only sign-inCopy Anchor Link

If the app requires sign-in, add the encrypted organization launch variable REVYL_SIGN_IN_SECRET to the recipe and enable the project's sign-in link:

run:
  start: HOSTNAME=0.0.0.0 node server.js
  port: 3000
  secret_names: [REVYL_SIGN_IN_SECRET]

session:
  auth_bypass:
    sign_in:
      path: /revyl-login
      secret: REVYL_SIGN_IN_SECRET

These fields contain the variable's name, never its value.

Add /revyl-login only to test deployments and issue a session through the app's normal auth flow. In the App Router, use app/revyl-login/route.ts or src/app/revyl-login/route.ts; an underscore-prefixed folder does not become a route. Keep the secret out of NEXT_PUBLIC_* values and browser code. Follow Web sign-in links for the verification contract.

Use a hosted preview insteadCopy Anchor Link

Follow Register a deployed preview. This works with your existing Next.js host without changing its deployment output to a standalone bundle.

Build and open a sessionCopy Anchor Link

revyl config validate
revyl build --profile preview --platform web
revyl device start --platform web --app <web-app-id>

Check the session and sign-in account, then stop it with:

revyl device stop --session-id <session-id>

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link

• Web runtime overview
• Web builds
• Sessions: Web sessions
• Proof of changes