Installation

Surf lets any website expose typed commands for AI agents. Install the packages you need and start building in minutes.

Installation#

Packages are grouped by where they run. Pick what you need:

Server — expose commands

Core framework — define commands, serve the manifest, mount middleware. Works with Express, Fastify, Hono, or raw Node.

npm install @surfjs/core

Next.js adapter — zero-config route handler for App Router.

npm install @surfjs/next

Browser — execute commands locally

Browser runtime — framework-agnostic window.surf dispatcher. Register local handlers that execute in the browser with zero network latency.

npm install @surfjs/web

React hooks — thin wrapper around @surfjs/web. useSurfCommands, SurfProvider, useSurfState, and SurfBadge.

npm install @surfjs/react

Vue composables — useSurfCommands, useSurf, useSurfState for Vue 3.

npm install @surfjs/vue

Svelte stores — surfCommands, surfState, surfExecute for Svelte 4/5.

npm install @surfjs/svelte

Note: @surfjs/react, @surfjs/vue, and @surfjs/svelte all depend on @surfjs/web — you don't need to install it separately when using a framework package.

Agent — discover & execute remotely

Client SDK — discover Surf-enabled sites, execute commands, run pipelines, manage sessions.

npm install @surfjs/client

CLI — inspect manifests, test commands, debug endpoints from your terminal.

npm install -g @surfjs/cli

Developer tools

Zod schema integration — type-safe parameter validation with Zod 3 or 4.

npm install @surfjs/zod

DevUI inspector — drop-in browser debugger for testing commands during development.

npm install -D @surfjs/devui

Common setups#

Full-stack Next.js (server + browser commands):

npm install @surfjs/core @surfjs/next @surfjs/react

Express API (server-only):

npm install @surfjs/core

React SPA (browser-only commands):

npm install @surfjs/react

AI agent (headless client):

npm install @surfjs/client