Next.js

Next.js#

The @surfjs/next package provides first-class Next.js App Router support with edge-compatible Web Standard Request/Response handling. Install it alongside @surfjs/core:

pnpm add @surfjs/next @surfjs/core

Create a catch-all route handler at app/api/surf/[...slug]/route.ts:

// app/api/surf/[...slug]/route.ts
import { createSurf } from '@surfjs/core'
import { createSurfRouteHandler } from '@surfjs/next'
 
const surf = await createSurf({
  name: 'My Next.js App',
  commands: {
    search: {
      description: 'Search products',
      params: { query: { type: 'string', required: true } },
      run: async ({ query }) => db.search(query),
    },
  },
})
 
// Returns { GET, POST } — export directly as Next.js route handlers
export const { GET, POST } = createSurfRouteHandler(surf)

This mounts the following endpoints under /api/surf/:

| Method | Path | Description | |--------|------|-------------| | GET | /.well-known/surf.json | Manifest (auto via middleware) | | GET / POST | /api/surf/execute | Command execution | | POST | /api/surf/pipeline | Pipeline execution | | POST | /api/surf/session/start | Start session | | POST | /api/surf/session/end | End session |

💡 Tip: When using @surfjs/next, pass basePath: '/api/surf/execute' to your SurfClient (or --base-path /api/surf/execute to the CLI) so the client targets the correct route.

import { SurfClient } from '@surfjs/client'
 
// Point the client at your Next.js app's execute endpoint
const client = await SurfClient.discover('https://my-app.vercel.app', {
  basePath: '/api/surf/execute',
})