create-surf-app 1.0.0-alpha.33 → 1.0.0-alpha.35

package/README.md

@@ -0,0 +1,64 @@
+# create-surf-app
+
+Scaffold a Surf app pre-wired with [`@surf-ai/sdk`](../sdk).
+
+## Usage
+
+```bash
+npm create surf-app@latest [project-name] [--template <vite|nextjs>]
+```
+
+- `project-name` — directory to create (defaults to current directory)
+- `--template` — `vite` (default) or `nextjs`
+
+Examples:
+
+```bash
+npm create surf-app@latest my-app
+npm create surf-app@latest my-app --template nextjs
+npm create surf-app@latest .  # scaffold into current dir
+```
+
+## Templates
+
+| Template | Stack |
+| --- | --- |
+| `vite` (default) | Vite + React + Express backend using `@surf-ai/sdk/server` |
+| `nextjs` | Next.js App Router with API route handlers using `@surf-ai/sdk/server` |
+
+## Environment variables
+
+`SURF_API_KEY` is the only secret you need to provide. Everything else has a sensible default — but `BASE_PATH` must be **defined** (empty string is fine and means root) because the scaffolds read it unconditionally.
+
+### `vite` template
+
+`backend/.env`:
+
+| Var | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `SURF_API_KEY` | yes (non-empty) | — | Bearer token for Surf upstream + protected runtime endpoints |
+| `BACKEND_PORT` | no | `3001` | Express server port |
+| `SURF_API_BASE_URL` | no | `https://api.asksurf.ai/gateway/v1` | Override Surf API base URL |
+
+`frontend/.env`:
+
+| Var | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `BASE_PATH` | yes (empty OK) | — | Vite base path (e.g. `/preview/abc/`); empty means root |
+| `PORT` | no | `5173` | Vite dev server port |
+| `BACKEND_PORT` | no | `3001` | Backend port the dev server proxies `/api` to |
+
+### `nextjs` template
+
+`.env`:
+
+| Var | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `SURF_API_KEY` | yes (non-empty) | — | Bearer token for Surf upstream + protected runtime endpoints |
+| `BASE_PATH` | yes (empty OK) | — | Next.js `basePath` (e.g. `/preview/abc`); empty means root |
+| `PORT` | no | `3000` | Next.js server port |
+| `SURF_API_BASE_URL` | no | `https://api.asksurf.ai/gateway/v1` | Override Surf API base URL |
+
+`SURF_API_KEY` is enforced at **dev/start** time, not build time — `npm run build` succeeds without it so CI builds don't need the secret.
+
+See [`@surf-ai/sdk` README](../sdk/README.md) for full SDK configuration and runtime details.

package/dist/templates/default/CLAUDE.md

@@ -69,27 +69,43 @@ exports.users = pgTable("users", {
 
 Tables are auto-created on startup and when `schema.js` changes (file watcher).
 
-Query the database in routes using `@surf-ai/sdk/db` — **not** Drizzle ORM query builder:
+Query the database in routes with `dbQuery(sql, params)` from `@surf-ai/sdk/db`. Drizzle ORM is **only** used to declare the schema — there is no Drizzle client, no `req.db` middleware, and no direct connection pool. `dbQuery` returns a pg-style result `{ rows, rowCount, fields }`, so destructure `rows`:
 
 ```js
 const { dbQuery } = require("@surf-ai/sdk/db");
 
 router.get("/", async (req, res) => {
-  const rows = await dbQuery("SELECT * FROM users ORDER BY created_at DESC");
+  const { rows } = await dbQuery(
+    "SELECT * FROM users ORDER BY created_at DESC"
+  );
   res.json(rows);
 });
 
 router.post("/", async (req, res) => {
   const { name } = req.body;
-  const [row] = await dbQuery(
+  const { rows } = await dbQuery(
     "INSERT INTO users (name) VALUES ($1) RETURNING *",
     [name]
   );
-  res.json(row);
+  res.json(rows[0]);
 });
 ```
 
-Database runs through an HTTP proxy — there is no direct `db` connection object or `req.db` middleware. Use `dbQuery(sql, params)` for all reads and writes.
+### Environment variables
+
+Only variables prefixed with `VITE_` are exposed to the Vite frontend (`import.meta.env.VITE_FOO`). To use a plain env var (e.g. `APP_TITLE`) in the UI, read it in a backend route and fetch it from the frontend:
+
+```js
+// backend/routes/config.js
+const express = require("express");
+const router = express.Router();
+
+router.get("/", (_req, res) => {
+  res.json({ title: process.env.APP_TITLE || "App" });
+});
+
+module.exports = router;
+```
 
 ## Do NOT modify
 

package/dist/templates/default/backend/package.json

@@ -5,7 +5,7 @@
     "dev": "node scripts/check-env.js node --watch server.js"
   },
   "dependencies": {
-    "@surf-ai/sdk": "1.0.0-alpha.33",
+    "@surf-ai/sdk": "1.0.0-alpha.35",
     "express": "4.22.1"
   }
 }

package/dist/templates/nextjs/CLAUDE.md

@@ -72,27 +72,31 @@ export const users = pgTable("users", {
 
 Tables are auto-synced on server start and when `db/schema.ts` changes in dev mode.
 
-Query the database in API routes using `@surf-ai/sdk/db` — **not** Drizzle ORM query builder:
+Query the database in API routes using the `db()` helper re-exported from `@/db`. Drizzle ORM is **only** used to declare the schema — there is no Drizzle client and no direct connection pool. `db(sql, params)` returns a pg-style result `{ rows, rowCount, fields }`, so destructure `rows`:
 
 ```ts
-import { dbQuery } from "@surf-ai/sdk/db";
+import { db } from "@/db";
 
 export async function GET() {
-  const rows = await dbQuery("SELECT * FROM users ORDER BY created_at DESC");
+  const { rows } = await db(
+    "SELECT * FROM users ORDER BY created_at DESC"
+  );
   return Response.json(rows);
 }
 
 export async function POST(request: Request) {
   const { name } = await request.json();
-  const [row] = await dbQuery(
+  const { rows } = await db(
     "INSERT INTO users (name) VALUES ($1) RETURNING *",
     [name]
   );
-  return Response.json(row);
+  return Response.json(rows[0]);
 }
 ```
 
-Database runs through an HTTP proxy — there is no direct `db` connection object or `req.db` middleware. Use `dbQuery(sql, params)` for all reads and writes.
+### Environment variables
+
+Only variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. To use a plain env var (e.g. `APP_TITLE`) in a client component, either read it in a server component / route handler and pass it down as a prop, or expose it through a backend route.
 
 ## Do NOT modify
 

package/dist/templates/nextjs/db/index.ts

@@ -3,6 +3,6 @@
 //
 // Usage in route handlers:
 //   import { db } from '@/db'
-//   const result = await db('SELECT * FROM users')
+//   const { rows } = await db('SELECT * FROM users')
 
 export { dbQuery as db, dbProvision, dbTables, dbTableSchema, dbStatus } from '@surf-ai/sdk/db'

package/dist/templates/nextjs/package.json

@@ -8,7 +8,7 @@
     "type-check": "tsc --noEmit --incremental"
   },
   "dependencies": {
-    "@surf-ai/sdk": "1.0.0-alpha.33",
+    "@surf-ai/sdk": "1.0.0-alpha.35",
     "@surf-ai/theme": "latest",
     "next": "15.5.14",
     "react": "19.2.4",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-surf-app",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.35",
   "description": "Scaffold a Surf app — Vite + React + Express + @surf-ai/sdk",
   "type": "module",
   "bin": {