{"id":21078,"library":"create-surf-app","title":"create-surf-app","description":"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.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install create-surf-app","lang":"bash","label":"npm"},{"cmd":"yarn add create-surf-app","lang":"bash","label":"yarn"},{"cmd":"pnpm add create-surf-app","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core SDK for Surf API integration; scaffolds include it as a dependency","package":"@surf-ai/sdk","optional":false},{"reason":"Backend server for Vite template","package":"express","optional":true},{"reason":"Frontend framework for both templates","package":"react","optional":true},{"reason":"Framework for Next.js template","package":"next","optional":true}],"imports":[{"note":"Use npm create (or yarn create/pnpm create) for the latest version; avoid npx which may use an older cached version.","wrong":"npx create-surf-app [project-name]","symbol":"create-surf-app","correct":"npm create surf-app@latest [project-name] [--template <vite|nextjs>]"},{"note":"Named export for the client; default export is not available.","wrong":"import SurfClient from '@surf-ai/sdk'","symbol":"@surf-ai/sdk","correct":"import { SurfClient } from '@surf-ai/sdk'"},{"note":"Server-side exports are in a separate subpath; importing from main package will not work.","wrong":"import { createSurfHandler } from '@surf-ai/sdk'","symbol":"@surf-ai/sdk/server","correct":"import { createSurfHandler } from '@surf-ai/sdk/server'"}],"quickstart":{"code":"npm create surf-app@latest my-surf-app\ncd my-surf-app\n# Set environment variables frontend/.env or .env as needed\n# SURF_API_KEY is required\nBACKEND_PORT=3001 npm run dev","lang":"javascript","description":"Scaffold a new Surf app with default Vite template, then run development servers."},"warnings":[{"fix":"Set BASE_PATH= in frontend/.env (Vite template) or .env (Next.js template); it can be empty.","message":"BASE_PATH must be defined (empty string is fine) in .env files; the scaffold reads it unconditionally.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set SURF_API_KEY in your production environment; CI can omit it if only building.","message":"SURF_API_KEY is enforced at dev/start time, not build time. CI builds will succeed without the key.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure frontend/.env has BASE_PATH and PORT, backend/.env has SURF_API_KEY and BACKEND_PORT.","message":"The Vite template uses two separate .env files: frontend/.env and backend/.env. Mixing them up will cause missing variables.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add SURF_API_KEY=your_key_here to backend/.env (Vite) or .env (Next.js).","cause":"Missing SURF_API_KEY environment variable at runtime.","error":"Error: SURF_API_KEY is required. Set it in your .env file."},{"fix":"Add BASE_PATH= to frontend/.env (Vite) or .env (Next.js). It can be an empty string.","cause":"BASE_PATH environment variable is missing; the scaffold reads it unconditionally.","error":"Error: BASE_PATH is not defined. Please set BASE_PATH in your .env file (empty string is okay)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}