Registry / web-framework / create-surf-app

create-surf-app

library1.0.4jsnpmunverified

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.

web-framework devops

npm install create-surf-app

package ↗

INSTALL

IMPORT

SIG · CREATE-SURF-APP

create-surf-app

web-frameworkjavascriptv1.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

create-surf-app

✓ npm create surf-app@latest [project-name] [--template <vite|nextjs>]

✗ npx create-surf-app [project-name]

Use npm create (or yarn create/pnpm create) for the latest version; avoid npx which may use an older cached version.

@surf-ai/sdk

✓ import { SurfClient } from '@surf-ai/sdk'

✗ import SurfClient from '@surf-ai/sdk'

Named export for the client; default export is not available.

@surf-ai/sdk/server

✓ import { createSurfHandler } from '@surf-ai/sdk/server'

✗ import { createSurfHandler } from '@surf-ai/sdk'

Server-side exports are in a separate subpath; importing from main package will not work.

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

create-surf-app --version

Debug

Known issues

gotchaBASE_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.

affects: >=1.0.0

gotchaSURF_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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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: BASE_PATH is not defined. Please set BASE_PATH in your .env file (empty string is okay).

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.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

@surf-ai/sdkrequiredCore SDK for Surf API integration; scaffolds include it as a dependency

expressoptionalBackend server for Vite template

reactoptionalFrontend framework for both templates

nextoptionalFramework for Next.js template

Agent activity

8 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/create-surf-app ↗