create-surf-app 1.0.0-alpha.34 → 1.0.0-alpha.35
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# create-surf-app
|
|
2
|
+
|
|
3
|
+
Scaffold a Surf app pre-wired with [`@surf-ai/sdk`](../sdk).
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm create surf-app@latest [project-name] [--template <vite|nextjs>]
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
- `project-name` — directory to create (defaults to current directory)
|
|
12
|
+
- `--template` — `vite` (default) or `nextjs`
|
|
13
|
+
|
|
14
|
+
Examples:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm create surf-app@latest my-app
|
|
18
|
+
npm create surf-app@latest my-app --template nextjs
|
|
19
|
+
npm create surf-app@latest . # scaffold into current dir
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Templates
|
|
23
|
+
|
|
24
|
+
| Template | Stack |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `vite` (default) | Vite + React + Express backend using `@surf-ai/sdk/server` |
|
|
27
|
+
| `nextjs` | Next.js App Router with API route handlers using `@surf-ai/sdk/server` |
|
|
28
|
+
|
|
29
|
+
## Environment variables
|
|
30
|
+
|
|
31
|
+
`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.
|
|
32
|
+
|
|
33
|
+
### `vite` template
|
|
34
|
+
|
|
35
|
+
`backend/.env`:
|
|
36
|
+
|
|
37
|
+
| Var | Required | Default | Purpose |
|
|
38
|
+
| --- | --- | --- | --- |
|
|
39
|
+
| `SURF_API_KEY` | yes (non-empty) | — | Bearer token for Surf upstream + protected runtime endpoints |
|
|
40
|
+
| `BACKEND_PORT` | no | `3001` | Express server port |
|
|
41
|
+
| `SURF_API_BASE_URL` | no | `https://api.asksurf.ai/gateway/v1` | Override Surf API base URL |
|
|
42
|
+
|
|
43
|
+
`frontend/.env`:
|
|
44
|
+
|
|
45
|
+
| Var | Required | Default | Purpose |
|
|
46
|
+
| --- | --- | --- | --- |
|
|
47
|
+
| `BASE_PATH` | yes (empty OK) | — | Vite base path (e.g. `/preview/abc/`); empty means root |
|
|
48
|
+
| `PORT` | no | `5173` | Vite dev server port |
|
|
49
|
+
| `BACKEND_PORT` | no | `3001` | Backend port the dev server proxies `/api` to |
|
|
50
|
+
|
|
51
|
+
### `nextjs` template
|
|
52
|
+
|
|
53
|
+
`.env`:
|
|
54
|
+
|
|
55
|
+
| Var | Required | Default | Purpose |
|
|
56
|
+
| --- | --- | --- | --- |
|
|
57
|
+
| `SURF_API_KEY` | yes (non-empty) | — | Bearer token for Surf upstream + protected runtime endpoints |
|
|
58
|
+
| `BASE_PATH` | yes (empty OK) | — | Next.js `basePath` (e.g. `/preview/abc`); empty means root |
|
|
59
|
+
| `PORT` | no | `3000` | Next.js server port |
|
|
60
|
+
| `SURF_API_BASE_URL` | no | `https://api.asksurf.ai/gateway/v1` | Override Surf API base URL |
|
|
61
|
+
|
|
62
|
+
`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.
|
|
63
|
+
|
|
64
|
+
See [`@surf-ai/sdk` README](../sdk/README.md) for full SDK configuration and runtime details.
|