create-surf-app 1.0.0-alpha.3 → 1.0.0-alpha.30

package/dist/{chunk-NZOL5GFZ.js → chunk-FDATV75D.js}

@@ -1,21 +1,16 @@
 // src/index.ts
 import fs from "fs";
-import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
-var DEFAULT_BACKEND_PORT = "3001";
 var VALID_TEMPLATES = ["vite", "nextjs"];
 async function createSurfApp({
   projectName = ".",
-  backendPort = process.env.BACKEND_PORT || DEFAULT_BACKEND_PORT,
-  previewBase = process.env.BASE_PATH,
   template: templateArg,
   logger = console.log
 } = {}) {
   const root = path.resolve(projectName);
   const name = path.basename(root);
   const template = validateTemplate(templateArg);
-  const validatedBackendPort = validatePort("backend", backendPort);
   const templateDir = resolveTemplateDir(template);
   logger(`
   Creating Surf app (${template}) in ${root}
@@ -23,7 +18,6 @@ async function createSurfApp({
   fs.mkdirSync(root, { recursive: true });
   copyDir(templateDir, root, root, logger);
   if (template === "nextjs") {
-    writeNextjsEnvFile(root, validatedBackendPort, previewBase);
     finalizePackageName(root, name);
     logger(`
 Done! Next steps:
@@ -35,19 +29,12 @@ Done! Next steps:
   Open http://localhost:3000
 `);
   } else {
-    writeEnvFiles(root, validatedBackendPort, previewBase);
     logger(`
 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
 `);
@@ -87,43 +74,12 @@ function copyDir(src, dest, root, logger) {
     logger(`  ${path.relative(root, destPath)}`);
   }
 }
-function validatePort(label, value) {
-  const port = Number.parseInt(value, 10);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new Error(`Invalid ${label} port: ${value}`);
-  }
-  return String(port);
-}
 function finalizePackageName(root, projectName) {
   const pkgPath = path.join(root, "package.json");
   if (!fs.existsSync(pkgPath)) return;
   const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
   pkg.name = projectName.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "surf-app";
-  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}${os.EOL}`);
-}
-function writeNextjsEnvFile(root, port, basePath) {
-  const envPath = path.join(root, ".env");
-  const envContent = [
-    `FRONTEND_PORT=${port}`,
-    `BASE_PATH=${basePath || ""}`,
-    "SURF_API_KEY="
-  ].join(os.EOL);
-  fs.writeFileSync(envPath, `${envContent}${os.EOL}`);
-}
-function writeEnvFiles(root, backendPort, previewBase) {
-  const backendEnvPath = path.join(root, "backend", ".env");
-  const frontendEnvPath = path.join(root, "frontend", ".env");
-  const backendEnv = [
-    `BACKEND_PORT=${backendPort}`,
-    "SURF_API_KEY="
-  ].join(os.EOL);
-  fs.writeFileSync(backendEnvPath, `${backendEnv}${os.EOL}`);
-  const frontendEnv = [
-    "FRONTEND_PORT=5173",
-    `BACKEND_PORT=${backendPort}`,
-    `BASE_PATH=${previewBase || ""}`
-  ].join(os.EOL);
-  fs.writeFileSync(frontendEnvPath, `${frontendEnv}${os.EOL}`);
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 
 export {

package/dist/cli.js

@@ -1,13 +1,10 @@
 #!/usr/bin/env node
 import {
   createSurfApp
-} from "./chunk-NZOL5GFZ.js";
+} from "./chunk-FDATV75D.js";
 
 // src/cli.ts
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
-  "--frontend-port",
-  "--backend-port",
-  "--preview-base",
   "--template"
 ]);
 function getFlag(args, name) {
@@ -35,9 +32,6 @@ function parseCliArgs(args) {
   }
   return {
     projectName: positionalArgs[0] || ".",
-    frontendPort: getFlag(args, "--frontend-port"),
-    backendPort: getFlag(args, "--backend-port"),
-    previewBase: getFlag(args, "--preview-base"),
     template: getFlag(args, "--template")
   };
 }

package/dist/index.js

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

package/dist/templates/default/CLAUDE.md

@@ -88,3 +88,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/.env.example

@@ -0,0 +1,2 @@
+BACKEND_PORT=3001
+SURF_API_KEY=

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

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

package/dist/templates/default/backend/scripts/check-env.js

@@ -0,0 +1,40 @@
+/**
+ * Validates required env vars before running a command.
+ * Loads .env if it exists (optional convenience), then checks vars.
+ *
+ * Dev/start: BACKEND_PORT, SURF_API_KEY
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { execSync } = require('node:child_process')
+
+// Load .env if it exists (convenience — env vars can come from anywhere)
+const envPath = path.join(process.cwd(), '.env')
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq < 0) continue
+    const key = trimmed.slice(0, eq)
+    const val = trimmed.slice(eq + 1)
+    if (!process.env[key]) process.env[key] = val
+  }
+}
+
+const args = process.argv.slice(2)
+
+const required = ['BACKEND_PORT', 'SURF_API_KEY']
+const missing = required.filter(k => !process.env[k])
+
+if (missing.length > 0) {
+  console.error(`\n❌ Missing required env vars: ${missing.join(', ')}`)
+  console.error(`   Set them in your environment or copy .env.example to .env\n`)
+  process.exit(1)
+}
+
+try {
+  execSync(args.join(' '), { stdio: 'inherit', env: process.env })
+} catch (e) {
+  process.exit(e.status || 1)
+}

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

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

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

@@ -4,8 +4,8 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
-    "build": "npm run build:client && npm run build:server",
+    "dev": "node scripts/check-env.cjs vite",
+    "build": "node scripts/check-env.cjs npm run build:client && npm run build:server",
     "build:client": "vite build --outDir dist/client",
     "build:server": "vite build --ssr src/entry-server.tsx --outDir dist/server",
     "lint": "eslint .",
@@ -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

@@ -0,0 +1,51 @@
+/**
+ * Validates required env vars before running a command.
+ * Loads .env manually, checks vars, then execs the actual command.
+ *
+ * Build: BASE_PATH (defined, can be empty), BACKEND_PORT
+ * Dev: PORT, BACKEND_PORT, BASE_PATH
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { execSync } = require('node:child_process')
+
+// Load .env manually (Vite doesn't load non-VITE_ vars into process.env)
+const envPath = path.join(process.cwd(), '.env')
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq < 0) continue
+    const key = trimmed.slice(0, eq)
+    const val = trimmed.slice(eq + 1)
+    if (!process.env[key]) process.env[key] = val
+  }
+}
+
+const args = process.argv.slice(2)
+const isBuild = args.some(a => a.includes('build'))
+
+// Vars that must be non-empty
+const requiredNonEmpty = isBuild
+  ? ['BACKEND_PORT']
+  : ['PORT', 'BACKEND_PORT']
+
+// Vars that must be defined (empty is ok — BASE_PATH="" means root)
+const requiredDefined = ['BASE_PATH']
+
+const missingNonEmpty = requiredNonEmpty.filter(k => !process.env[k])
+const missingDefined = requiredDefined.filter(k => process.env[k] === undefined)
+const missing = [...missingNonEmpty, ...missingDefined]
+
+if (missing.length > 0) {
+  console.error(`\n❌ Missing required env vars: ${missing.join(', ')}`)
+  console.error(`   Set them in your environment or copy .env.example to .env\n`)
+  process.exit(1)
+}
+
+try {
+  execSync(args.join(' '), { stdio: 'inherit', env: process.env })
+} catch (e) {
+  process.exit(e.status || 1)
+}

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

@@ -1,25 +1,12 @@
 import path from 'path'
-import { defineConfig, loadEnv } from 'vite'
+import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 
-function readRequiredPort(
-  env: Record<string, string>,
-  name: 'BACKEND_PORT' | 'FRONTEND_PORT',
-) {
-  const value = env[name]
-  const port = Number.parseInt(value || '', 10)
-  if (!Number.isInteger(port)) {
-    throw new Error(`Missing required ${name} in frontend/.env`)
-  }
-  return port
-}
-
-export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, process.cwd(), '')
-  const frontendPort = readRequiredPort(env, 'FRONTEND_PORT')
-  const backendPort = readRequiredPort(env, 'BACKEND_PORT')
-  const base = env.BASE_PATH || './'
+export default defineConfig(() => {
+  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('/')
   const apiBasePrefix = hasAbsBase ? base.replace(/\/$/, '') : ''
 
@@ -35,11 +22,10 @@ export default defineConfig(({ mode }) => {
     plugins: [react(), tailwindcss()],
     server: {
       host: '0.0.0.0',
-      port: frontendPort,
+      port: frontendPort || undefined,
       proxy: {
         [`${apiBasePrefix}/api`]: backendProxy,
       },
-      // Keep the HMR socket under the preview base path.
       hmr: {
         path: 'ws/vite-hmr',
       },
@@ -51,8 +37,6 @@ export default defineConfig(({ mode }) => {
       dedupe: ['react', 'react-dom'],
       preserveSymlinks: true,
     },
-    // Pre-bundle the deps touched during the initial boot path so cold starts
-    // do not race Vite's lazy dependency optimizer.
     optimizeDeps: {
       include: [
         'react',

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

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

package/dist/templates/nextjs/CLAUDE.md

@@ -79,7 +79,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/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.3",
+    "@surf-ai/sdk": "1.0.0-alpha.30",
     "@surf-ai/theme": "latest",
-    "next": "15.3.3",
+    "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

@@ -26,22 +26,24 @@ if (fs.existsSync(envPath)) {
 const args = process.argv.slice(2)
 const isBuild = args.includes('build')
 
-const required = isBuild
-  ? ['BASE_PATH', 'SURF_API_KEY']
-  : ['FRONTEND_PORT', 'BASE_PATH', 'SURF_API_KEY']
+// Vars that must be non-empty
+const requiredNonEmpty = isBuild
+  ? []
+  : ['PORT', 'SURF_API_KEY']
 
-const missing = required.filter(k => !process.env[k])
+// Vars that must be defined (empty is ok — e.g. BASE_PATH="" means root)
+const requiredDefined = ['BASE_PATH']
+
+const missingNonEmpty = requiredNonEmpty.filter(k => !process.env[k])
+const missingDefined = requiredDefined.filter(k => process.env[k] === undefined)
+const missing = [...missingNonEmpty, ...missingDefined]
 
 if (missing.length > 0) {
-  console.error(`\n❌ Missing required env vars in .env: ${missing.join(', ')}\n`)
+  console.error(`\n❌ Missing required env vars: ${missing.join(', ')}`)
+  console.error(`   Set them in your environment or copy .env.example to .env\n`)
   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.3",
+  "version": "1.0.0-alpha.30",
   "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"
-  }
-}