create-surf-app 1.0.0-alpha.9 → 1.0.3

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

@@ -15,13 +15,14 @@ Use `@surf-ai/sdk/server` in backend routes to talk to Surf data APIs.
 
 ```js
 const { dataApi } = require("@surf-ai/sdk/server");
-const data = await dataApi.market.price({ symbol: "BTC" });
-const holders = await dataApi.token.holders({
-  address: "0x...",
-  chain: "ethereum",
-});
-// Escape hatch for new endpoints:
-const raw = await dataApi.get("newcategory/endpoint", { foo: "bar" });
+
+// Typed methods per domain — check `@surf-ai/sdk/server` typings for the
+// available method on each domain and its exact parameter shape. Don't
+// copy parameters from one method to another; shapes differ per endpoint.
+const data = await dataApi.<domain>.<method>({ /* params */ });
+
+// Escape hatch for endpoints not yet in the typed API:
+const raw = await dataApi.get("<domain>/<endpoint>", { /* params */ });
 ```
 
 ## Structure
@@ -48,11 +49,7 @@ backend/db/schema.js       - define database tables
 | `/api/cron/:id`      | DELETE | Delete a cron task                                     |
 | `/api/cron/:id/run`  | POST   | Manually trigger a cron task                           |
 
-Auto-registered from `backend/routes/*.js`:
-| File | Endpoint |
-|------|----------|
-| `routes/btc.js` | `/api/btc` |
-| `routes/portfolio.js` | `/api/portfolio` |
+Auto-registered: any file at `backend/routes/<name>.js` is mounted at `/api/<name>`.
 
 ## Database
 
@@ -68,7 +65,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
 

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.9",
+    "@surf-ai/sdk": "1.0.3",
     "express": "4.22.1"
   }
 }

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/src/components/ui/resizable.tsx

@@ -1,13 +1,13 @@
 import { GripVertical } from "lucide-react"
-import * as ResizablePrimitive from "react-resizable-panels"
+import { Group, Panel, Separator } from "react-resizable-panels"
 
 import { cn } from "@/lib/utils"
 
 const ResizablePanelGroup = ({
   className,
   ...props
-}: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) => (
-  <ResizablePrimitive.PanelGroup
+}: React.ComponentProps<typeof Group>) => (
+  <Group
     className={cn(
       "flex h-full w-full data-[panel-group-direction=vertical]:flex-col",
       className
@@ -16,16 +16,16 @@ const ResizablePanelGroup = ({
   />
 )
 
-const ResizablePanel = ResizablePrimitive.Panel
+const ResizablePanel = Panel
 
 const ResizableHandle = ({
   withHandle,
   className,
   ...props
-}: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & {
+}: React.ComponentProps<typeof Separator> & {
   withHandle?: boolean
 }) => (
-  <ResizablePrimitive.PanelResizeHandle
+  <Separator
     className={cn(
       "relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1 data-[panel-group-direction=vertical]:h-px data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-1 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0 [&[data-panel-group-direction=vertical]>div]:rotate-90",
       className
@@ -37,7 +37,7 @@ const ResizableHandle = ({
         <GripVertical className="h-2.5 w-2.5" />
       </div>
     )}
-  </ResizablePrimitive.PanelResizeHandle>
+  </Separator>
 )
 
 export { ResizablePanelGroup, ResizablePanel, ResizableHandle }

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

@@ -3,6 +3,9 @@ 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

@@ -8,12 +8,12 @@
     "type-check": "tsc --noEmit --incremental"
   },
   "dependencies": {
-    "@surf-ai/sdk": "1.0.0-alpha.9",
+    "@surf-ai/sdk": "1.0.3",
     "@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",
@@ -59,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-surf-app",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.3",
   "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,
-  "workspaces": ["backend", "frontend"],
-  "scripts": {
-    "dev": "concurrently \"npm run dev --workspace backend\" \"npm run dev --workspace frontend\""
-  },
-  "devDependencies": {
-    "concurrently": "^9.0.0"
-  }
-}