create-surf-app 1.0.0-alpha.4 → 1.0.0-alpha.40

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/{chunk-BV3XIPFM.js → chunk-FDATV75D.js}

@@ -33,14 +33,8 @@ Done! Next steps:
 Done! Next steps:
 
   cd ${name}
-  cd backend && npm install && cd ..
-  cd frontend && npm install && cd ..
-
-  # Start backend
-  cd backend && npm run dev &
-
-  # Start frontend
-  cd frontend && npm run dev
+  npm install
+  npm run dev
 
   Open the local URL printed by Vite
 `);

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createSurfApp
-} from "./chunk-BV3XIPFM.js";
+} from "./chunk-FDATV75D.js";
 
 // src/cli.ts
 var VALUE_FLAGS = /* @__PURE__ */ new Set([

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createSurfApp
-} from "./chunk-BV3XIPFM.js";
+} from "./chunk-FDATV75D.js";
 export {
   createSurfApp
 };

package/dist/templates/default/CLAUDE.md

@@ -68,7 +68,44 @@ exports.users = pgTable("users", {
 ```
 
 Tables are auto-created on startup and when `schema.js` changes (file watcher).
-The agent can also call `POST /api/__sync-schema` explicitly after editing.
+
+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"
+  );
+  res.json(rows);
+});
+
+router.post("/", async (req, res) => {
+  const { name } = req.body;
+  const { rows } = await dbQuery(
+    "INSERT INTO users (name) VALUES ($1) RETURNING *",
+    [name]
+  );
+  res.json(rows[0]);
+});
+```
+
+### 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
 
@@ -88,3 +125,23 @@ The agent can also call `POST /api/__sync-schema` explicitly after editing.
 - Do not bypass your backend routes from the frontend
 - Frontend packages are pre-installed - check `package.json` before installing
 - Default to a dark theme unless the user explicitly asks for a different visual direction.
+
+## Design
+
+### Avoid AI-default patterns
+- No colored icon boxes next to metrics (the blue-bg-with-icon KPI pattern)
+- No gradient avatar circles with initials
+- No "Built with React · Tailwind" footers
+- No AI copywriting: "Elevate", "Seamless", "Unleash", "Delve", "Next-Gen"
+- No "Oops!" error messages — be direct ("Failed to load. Try again.")
+- No round placeholder numbers ($100.00) — use realistic data ($847.29)
+- Sentence case on headings, not Title Case On Every Word
+- Icons should aid scanning, not decorate — omit when the label is clear
+
+### ECharts
+- Flat style: show primary axis line, dashed split lines, transparent chart bg
+- Custom tooltip formatter with dash indicators (12×2.5px bars, not default circle dots)
+- Legend: type "plain", icon "roundRect", itemWidth 12, itemHeight 3
+- Prefer timeframe tabs (7D/30D/90D/1Y/All) over dataZoom for time series
+- Default to theme visualizer palette; override when semantics demand it (red/green for gain/loss, sequential scales for heatmaps)
+- Dark mode: parameterize tooltip bg, axis colors, split line colors via resolvedTheme

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

@@ -2,11 +2,10 @@
   "name": "backend",
   "private": true,
   "scripts": {
-    "start": "node scripts/check-env.js node server.js",
     "dev": "node scripts/check-env.js node --watch server.js"
   },
   "dependencies": {
-    "@surf-ai/sdk": "1.0.0-alpha.4",
+    "@surf-ai/sdk": "1.0.0-alpha.40",
     "express": "4.22.1"
   }
 }

package/dist/templates/default/frontend/.env.example

@@ -1,3 +1,3 @@
-FRONTEND_PORT=5173
+PORT=5173
 BACKEND_PORT=3001
 BASE_PATH=

package/dist/templates/default/frontend/package.json

@@ -78,6 +78,6 @@
     "tw-animate-css": "1.4.0",
     "typescript-eslint": "8.57.1",
     "typescript": "5.9.3",
-    "vite": "6.4.1"
+    "vite": "6.4.2"
   }
 }

package/dist/templates/default/frontend/scripts/check-env.cjs

@@ -3,7 +3,7 @@
  * Loads .env manually, checks vars, then execs the actual command.
  *
  * Build: BASE_PATH (defined, can be empty), BACKEND_PORT
- * Dev: FRONTEND_PORT, BACKEND_PORT, BASE_PATH
+ * Dev: PORT, BACKEND_PORT, BASE_PATH
  */
 const fs = require('node:fs')
 const path = require('node:path')
@@ -29,7 +29,7 @@ const isBuild = args.some(a => a.includes('build'))
 // Vars that must be non-empty
 const requiredNonEmpty = isBuild
   ? ['BACKEND_PORT']
-  : ['FRONTEND_PORT', 'BACKEND_PORT']
+  : ['PORT', 'BACKEND_PORT']
 
 // Vars that must be defined (empty is ok — BASE_PATH="" means root)
 const requiredDefined = ['BASE_PATH']

package/dist/templates/default/frontend/vite.config.ts

@@ -4,7 +4,7 @@ import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 
 export default defineConfig(() => {
-  const frontendPort = Number.parseInt(process.env.FRONTEND_PORT || '', 10)
+  const frontendPort = Number.parseInt(process.env.PORT || '', 10)
   const backendPort = Number.parseInt(process.env.BACKEND_PORT || '', 10)
   const base = process.env.BASE_PATH || './'
   const hasAbsBase = base.startsWith('/')

package/dist/templates/nextjs/.env.example

@@ -1,3 +1,3 @@
-FRONTEND_PORT=3000
+PORT=3000
 BASE_PATH=
 SURF_API_KEY=

package/dist/templates/nextjs/CLAUDE.md

@@ -72,6 +72,32 @@ 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 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 { db } from "@/db";
+
+export async function GET() {
+  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 { rows } = await db(
+    "INSERT INTO users (name) VALUES ($1) RETURNING *",
+    [name]
+  );
+  return Response.json(rows[0]);
+}
+```
+
+### 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
 
 - `instrumentation.ts` - server boot (schema sync, cron)
@@ -79,7 +105,7 @@ Tables are auto-synced on server start and when `db/schema.ts` changes in dev mo
 - `db/index.ts` - database connection
 - `lib/boot.ts` - infrastructure (schema sync, cron init)
 - `app/layout.tsx` - root layout and providers
-- `app/providers.tsx` - client-side providers (QueryClient, theme)
+- `app/providers.tsx` - client-side preview bridge hooks
 - `eslint.config.mjs` - lint rules
 - `globals.css` - only imports, do not add styles here (use Tailwind classes)
 

package/dist/templates/nextjs/app/providers.tsx

@@ -1,23 +1,35 @@
 "use client"
 
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
-import { useState } from "react"
+import { useEffect } from "react"
 
-export function Providers({ children }: { children: React.ReactNode }) {
-  const [queryClient] = useState(
-    () =>
-      new QueryClient({
-        defaultOptions: {
-          queries: {
-            refetchOnWindowFocus: false,
-            retry: 3,
-            staleTime: 30 * 1000,
-          },
-        },
-      })
-  )
+// Notify parent frame that the app has rendered.
+// DO NOT REMOVE — the hosting app uses this to dismiss the loading overlay.
+function useSurfAppReady() {
+  useEffect(() => {
+    try {
+      window.parent.postMessage({ type: "surf-app-ready" }, "*")
+    } catch {
+      /* cross-origin — ignore */
+    }
+  }, [])
+}
 
-  return (
-    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
-  )
+// Patch fetch so `/api/*` calls automatically include basePath.
+// Without this, `fetch('/api/...')` hits the parent app's routes instead of
+// the preview dev server's API routes.
+// DO NOT REMOVE — this is required for the preview proxy architecture.
+const _basePath = process.env.NEXT_PUBLIC_BASE_PATH || ""
+if (typeof window !== "undefined" && _basePath) {
+  const _origFetch = window.fetch
+  window.fetch = function patchedFetch(this: typeof globalThis, input: RequestInfo | URL, init?: RequestInit) {
+    if (typeof input === "string" && input.startsWith("/api/")) {
+      input = _basePath + input
+    }
+    return _origFetch.call(this, input, init)
+  } as typeof window.fetch
+}
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  useSurfAppReady()
+  return children
 }

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/next.config.ts

@@ -1,7 +1,11 @@
 import type { NextConfig } from 'next'
 
 const nextConfig: NextConfig = {
+  output: 'standalone',
   basePath: process.env.BASE_PATH!.replace(/\/+$/, ''),
+  env: {
+    NEXT_PUBLIC_BASE_PATH: process.env.BASE_PATH!.replace(/\/+$/, ''),
+  },
   serverExternalPackages: ['@surf-ai/sdk', 'drizzle-orm', 'drizzle-kit', 'croner'],
 }
 

package/dist/templates/nextjs/package.json

@@ -4,17 +4,16 @@
   "scripts": {
     "dev": "node scripts/check-env.js next dev",
     "build": "node scripts/check-env.js next build",
-    "start": "node scripts/check-env.js next start",
     "lint": "eslint .",
     "type-check": "tsc --noEmit --incremental"
   },
   "dependencies": {
-    "@surf-ai/sdk": "1.0.0-alpha.4",
+    "@surf-ai/sdk": "1.0.0-alpha.40",
     "@surf-ai/theme": "latest",
     "next": "15.5.14",
     "react": "19.2.4",
     "react-dom": "19.2.4",
-    "drizzle-orm": "0.44.2",
+    "drizzle-orm": "0.45.2",
     "drizzle-kit": "0.31.1",
     "croner": "9.1.0",
     "class-variance-authority": "0.7.1",
@@ -60,8 +59,6 @@
     "@hookform/resolvers": "5.2.2",
     "date-fns": "4.1.0",
     "zod": "3.25.76",
-    "@tanstack/react-query": "5.94.5",
-    "@tanstack/query-core": "5.94.5",
     "scheduler": "0.27.0"
   },
   "devDependencies": {

package/dist/templates/nextjs/scripts/check-env.js

@@ -29,7 +29,7 @@ const isBuild = args.includes('build')
 // Vars that must be non-empty
 const requiredNonEmpty = isBuild
   ? []
-  : ['FRONTEND_PORT', 'SURF_API_KEY']
+  : ['PORT', 'SURF_API_KEY']
 
 // Vars that must be defined (empty is ok — e.g. BASE_PATH="" means root)
 const requiredDefined = ['BASE_PATH']
@@ -44,11 +44,6 @@ if (missing.length > 0) {
   process.exit(1)
 }
 
-// Pass FRONTEND_PORT as PORT so Next.js uses it
-if (process.env.FRONTEND_PORT) {
-  process.env.PORT = process.env.FRONTEND_PORT
-}
-
 // Run the actual command
 try {
   execSync(args.join(' '), { stdio: 'inherit', env: process.env })

package/package.json

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

package/dist/templates/default/package.json

@@ -1,11 +0,0 @@
-{
-  "name": "surf-app",
-  "private": true,
-  "scripts": {
-    "dev": "concurrently \"npm run dev --prefix backend\" \"npm run dev --prefix frontend\"",
-    "install:all": "cd backend && npm install && cd ../frontend && npm install"
-  },
-  "devDependencies": {
-    "concurrently": "^9.0.0"
-  }
-}