create-surf-app

1.0.4 verified Mon Apr 27 auth: no javascript

Scaffolding CLI tool for Surf applications, integrating Vite + React + Express or Next.js with @surf-ai/sdk. Current stable version is 1.0.4. Release cadence is ad-hoc as part of the Surf monorepo. Key differentiators: provides ready-to-use templates pre-configured with backend and frontend, supports both Vite and Next.js, enforces SURF_API_KEY at runtime not build time, and requires BASE_PATH to be set even if empty.

Common errors

error Error: SURF_API_KEY is required. Set it in your .env file. ↓

cause Missing SURF_API_KEY environment variable at runtime.

fix

Add SURF_API_KEY=your_key_here to backend/.env (Vite) or .env (Next.js).

error Error: BASE_PATH is not defined. Please set BASE_PATH in your .env file (empty string is okay). ↓

cause BASE_PATH environment variable is missing; the scaffold reads it unconditionally.

fix

Add BASE_PATH= to frontend/.env (Vite) or .env (Next.js). It can be an empty string.

Warnings

gotcha BASE_PATH must be defined (empty string is fine) in .env files; the scaffold reads it unconditionally. ↓

fix Set BASE_PATH= in frontend/.env (Vite template) or .env (Next.js template); it can be empty.

gotcha SURF_API_KEY is enforced at dev/start time, not build time. CI builds will succeed without the key. ↓

fix Set SURF_API_KEY in your production environment; CI can omit it if only building.

gotcha The Vite template uses two separate .env files: frontend/.env and backend/.env. Mixing them up will cause missing variables. ↓

fix Ensure frontend/.env has BASE_PATH and PORT, backend/.env has SURF_API_KEY and BACKEND_PORT.

Install

npm install create-surf-app

yarn add create-surf-app

pnpm add create-surf-app

Imports

create-surf-app
wrong
```
npx create-surf-app [project-name]
```
correct
```
npm create surf-app@latest [project-name] [--template <vite|nextjs>]
```
Use npm create (or yarn create/pnpm create) for the latest version; avoid npx which may use an older cached version.
@surf-ai/sdk
wrong
```
import SurfClient from '@surf-ai/sdk'
```
correct
```
import { SurfClient } from '@surf-ai/sdk'
```
Named export for the client; default export is not available.
@surf-ai/sdk/server
wrong
```
import { createSurfHandler } from '@surf-ai/sdk'
```
correct
```
import { createSurfHandler } from '@surf-ai/sdk/server'
```
Server-side exports are in a separate subpath; importing from main package will not work.

Quickstart

Scaffold a new Surf app with default Vite template, then run development servers.

npm create surf-app@latest my-surf-app
cd my-surf-app
# Set environment variables frontend/.env or .env as needed
# SURF_API_KEY is required
BACKEND_PORT=3001 npm run dev