create-wervt 0.2.13 → 0.2.15
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/package.json
CHANGED
package/template/AGENTS.md
CHANGED
|
@@ -31,6 +31,18 @@ Pick the UI stack by the kind of app:
|
|
|
31
31
|
|
|
32
32
|
Reka UI primitives are fine inside a Nuxt UI app for a one-off component Nuxt UI doesn't have.
|
|
33
33
|
|
|
34
|
+
Icons: the isolate can't reach the Iconify API, so install every icon collection the app uses as
|
|
35
|
+
a dev dependency when adding Nuxt UI (or `@nuxt/icon`): `pnpm add -D @iconify-json/lucide` (Nuxt
|
|
36
|
+
UI's own icons are Lucide), plus `@iconify-json/<name>` for each other prefix you use (`i-<name>-…`).
|
|
37
|
+
@nuxt/icon bundles the locally installed collections into the server by itself; `@wervt/nuxt` only
|
|
38
|
+
stops the server from falling back to the API and warns on build when Lucide is missing (the full
|
|
39
|
+
`@iconify/json` package counts too).
|
|
40
|
+
|
|
41
|
+
OG images (`defineOgImage`): `pnpm add nuxt-og-image @takumi-rs/core @takumi-rs/wasm`. The isolate
|
|
42
|
+
can't load native renderers, so `@wervt/nuxt` switches nuxt-og-image to WebAssembly; don't set
|
|
43
|
+
`ogImage.compatibility` yourself. PNG only (no sharp). A private app's `/_og/…` images need a
|
|
44
|
+
login, so chats can't show them: use `wervt: { preview }` (below) for its shared links.
|
|
45
|
+
|
|
34
46
|
## Server routes
|
|
35
47
|
|
|
36
48
|
Use `defineEventHandler` and friends from `nuxt/server` (never `h3` or `nitro/h3`), and validate
|
|
@@ -59,6 +71,29 @@ export default defineEventHandler(async (event) => {
|
|
|
59
71
|
- Throw `createError({ status: 404, message: '…' })` for errors.
|
|
60
72
|
- Cookies and sessions: `getCookie`, `setCookie`, `useSession` from `nuxt/server`.
|
|
61
73
|
- Nothing is auto-imported on the server: import everything explicitly.
|
|
74
|
+
- Configuration and secrets: `runtimeConfig`, see below. No `process.env` in app code.
|
|
75
|
+
|
|
76
|
+
### Configuration and secrets
|
|
77
|
+
|
|
78
|
+
Declare every setting and secret in `runtimeConfig` in `nuxt.config.ts`, with an empty or default
|
|
79
|
+
value, and read it with `useRuntimeConfig()` from `nuxt/server` (in Vue code: `useRuntimeConfig()`,
|
|
80
|
+
`public` keys only). The defaults type it, and keys outside `public` never reach the browser.
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
// nuxt.config.ts
|
|
84
|
+
runtimeConfig: { weatherApiKey: '', public: { mapStyle: 'light' } },
|
|
85
|
+
|
|
86
|
+
// server/api/weather.get.ts
|
|
87
|
+
const { weatherApiKey } = useRuntimeConfig()
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- Values come from `wervt env <app> --set NUXT_<KEY>=…`, applied from the next request without a
|
|
91
|
+
deploy. The name is the key in SCREAMING_SNAKE_CASE with `NUXT_` in front: `weatherApiKey` →
|
|
92
|
+
`NUXT_WEATHER_API_KEY`, `public.mapStyle` → `NUXT_PUBLIC_MAP_STYLE`.
|
|
93
|
+
- Only declared keys are overridden: a `NUXT_*` variable without a key in `runtimeConfig` is ignored.
|
|
94
|
+
- Locally they come from `.env` (gitignored) with the same names.
|
|
95
|
+
- `server/api/example-secret.get.ts` shows the pattern with `exampleSecret`; replace it.
|
|
96
|
+
- `process.env` still works (and is typed by `@wervt/nuxt`), but don't use it for app settings.
|
|
62
97
|
|
|
63
98
|
## Database
|
|
64
99
|
|
|
@@ -123,6 +158,9 @@ const { data: todos, isLive } = await useShape('/api/shapes/todos')
|
|
|
123
158
|
- Column names are what the client sees, so keep them camelCase like the schema keys (no
|
|
124
159
|
snake_case `casing`).
|
|
125
160
|
- Never put secrets in a shape: list the `columns` a client may see.
|
|
161
|
+
- A shape route that needs a user answers 401 without one. `useShape` then has no
|
|
162
|
+
rows, no error and `unauthorized: true`, e.g. for the deploy's anonymous page check; no `v-if`
|
|
163
|
+
guard needed. Public apps can use `unauthorized` to show "sign in" instead of an empty state.
|
|
126
164
|
- Do auth checks in the shape route and restrict rows with `where`. Pass values as `params`,
|
|
127
165
|
never by building the SQL string:
|
|
128
166
|
|
|
@@ -142,6 +180,19 @@ version polling. For a banner in the app's own design, set `wervt: { updates: 'm
|
|
|
142
180
|
auto-imported) give the signed-in wervt user or nothing. Private apps always have one; public
|
|
143
181
|
apps only when the visitor signed in. It works with `ssr: false` too (no own `/api/me` needed). Link to `wervtLoginUrl(path)` / `wervtLogoutUrl(path)` as
|
|
144
182
|
external links. Never build your own login or OAuth.
|
|
183
|
+
- `user.role` is what they are to the app: `owner`, `member`, `admin` (wervt), `invited`,
|
|
184
|
+
`allowed` or `public`. Guard the app's admin features with
|
|
185
|
+
`requireWervtRole(event, 'owner', 'member', 'admin')` from `@wervt/nuxt/server`; don't keep
|
|
186
|
+
admin emails in env variables.
|
|
187
|
+
- Private apps show a link preview to visitors without a login (chats unfurling a shared link):
|
|
188
|
+
only the app name and icon unless `wervt: { preview: { title, description, image: '/og.png' } }`
|
|
189
|
+
is set (`true` takes them from `app.head`; `false` turns it off). Put the image (1200×630) in
|
|
190
|
+
`public/`. Ask before adding a description or image to a private app: they're visible to anyone
|
|
191
|
+
with the link.
|
|
192
|
+
- Users inviting others (leagues, rooms, shared boards): make the app invite-only
|
|
193
|
+
(`wervt access <app> --invite`, ask the user first) and call
|
|
194
|
+
`useWervtAccess(event).invite(email)` (`revoke`, `list`) from `@wervt/nuxt/server` in a route.
|
|
195
|
+
The runtime still guards every request; don't build your own member list or invite tokens.
|
|
145
196
|
- For your own state (anonymous visitors too), use `useSession(event, { name })` from
|
|
146
197
|
`nuxt/server`. The secret is set by wervt.
|
|
147
198
|
|
|
@@ -309,4 +360,22 @@ Queries are LogsQL. Logs may contain user data: quote only what's needed.
|
|
|
309
360
|
- `pnpm exec vp check --fix`: format, lint and type check. Run it before finishing.
|
|
310
361
|
- Deploys: pushing to `main` deploys through `.github/workflows/deploy.yml`.
|
|
311
362
|
`pnpm exec wervt releases <app>` lists releases with their commits. Don't deploy, roll back or
|
|
312
|
-
create tokens unless asked.
|
|
363
|
+
create deploy tokens unless asked.
|
|
364
|
+
|
|
365
|
+
## Checking the deployed app
|
|
366
|
+
|
|
367
|
+
A private app sends curl and headless browsers to the login. After a deploy, check protected
|
|
368
|
+
routes and pages yourself instead of asking a human to: `wervt token` mints a short-lived token
|
|
369
|
+
(15 minutes, `--ttl 1h` at most) for your CLI account on this app, and `useWervtUser(event)` sees
|
|
370
|
+
that account.
|
|
371
|
+
|
|
372
|
+
```bash
|
|
373
|
+
TOKEN=$(pnpm exec wervt token <app>)
|
|
374
|
+
curl -sH "Authorization: Bearer $TOKEN" https://<app>.wervt.app/api/…
|
|
375
|
+
pnpm exec wervt token <app> --cookie > /tmp/wervt-cookie.json # for a headless browser
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
In Playwright: `await context.addCookies([JSON.parse(cookieJson)])`, then open the app and check the
|
|
379
|
+
pages you changed (icons, uploads, forms). It needs a `wervt login` account that owns, is a member
|
|
380
|
+
of, or administers the app; deploy and read tokens can't mint one. Don't write the token to files
|
|
381
|
+
or commits. Requests made with it are tagged `agentToken` in the logs.
|
|
@@ -1,18 +1,43 @@
|
|
|
1
1
|
{
|
|
2
|
-
"
|
|
2
|
+
"type": "base",
|
|
3
|
+
"version": "9",
|
|
3
4
|
"dialect": "postgres",
|
|
4
5
|
"id": "89541799-b7fd-4ea4-bc66-6c6a95f8abf6",
|
|
5
6
|
"prevIds": [
|
|
6
7
|
"00000000-0000-0000-0000-000000000000"
|
|
7
8
|
],
|
|
9
|
+
"footprints": [
|
|
10
|
+
{
|
|
11
|
+
"statementType": "create_table",
|
|
12
|
+
"statementTarget": [
|
|
13
|
+
"table",
|
|
14
|
+
"public",
|
|
15
|
+
"todos"
|
|
16
|
+
],
|
|
17
|
+
"writes": [
|
|
18
|
+
"s|tbl|public.todos",
|
|
19
|
+
"n|tbl|public.todos",
|
|
20
|
+
"e|tbl|public.todos",
|
|
21
|
+
"n|rel|public.todos",
|
|
22
|
+
"n|type|public.todos",
|
|
23
|
+
"n|rel|public.todos_pkey"
|
|
24
|
+
],
|
|
25
|
+
"reads": [
|
|
26
|
+
"n|sch|public"
|
|
27
|
+
]
|
|
28
|
+
}
|
|
29
|
+
],
|
|
8
30
|
"ddl": [
|
|
9
31
|
{
|
|
10
|
-
"
|
|
32
|
+
"schema": "public",
|
|
11
33
|
"name": "todos",
|
|
12
|
-
"
|
|
13
|
-
"
|
|
34
|
+
"isRlsEnabled": false,
|
|
35
|
+
"entityType": "tables"
|
|
14
36
|
},
|
|
15
37
|
{
|
|
38
|
+
"schema": "public",
|
|
39
|
+
"table": "todos",
|
|
40
|
+
"name": "id",
|
|
16
41
|
"type": "serial",
|
|
17
42
|
"typeSchema": null,
|
|
18
43
|
"notNull": true,
|
|
@@ -20,12 +45,12 @@
|
|
|
20
45
|
"default": null,
|
|
21
46
|
"generated": null,
|
|
22
47
|
"identity": null,
|
|
23
|
-
"
|
|
24
|
-
"entityType": "columns",
|
|
25
|
-
"schema": "public",
|
|
26
|
-
"table": "todos"
|
|
48
|
+
"entityType": "columns"
|
|
27
49
|
},
|
|
28
50
|
{
|
|
51
|
+
"schema": "public",
|
|
52
|
+
"table": "todos",
|
|
53
|
+
"name": "title",
|
|
29
54
|
"type": "text",
|
|
30
55
|
"typeSchema": null,
|
|
31
56
|
"notNull": true,
|
|
@@ -33,12 +58,12 @@
|
|
|
33
58
|
"default": null,
|
|
34
59
|
"generated": null,
|
|
35
60
|
"identity": null,
|
|
36
|
-
"
|
|
37
|
-
"entityType": "columns",
|
|
38
|
-
"schema": "public",
|
|
39
|
-
"table": "todos"
|
|
61
|
+
"entityType": "columns"
|
|
40
62
|
},
|
|
41
63
|
{
|
|
64
|
+
"schema": "public",
|
|
65
|
+
"table": "todos",
|
|
66
|
+
"name": "done",
|
|
42
67
|
"type": "boolean",
|
|
43
68
|
"typeSchema": null,
|
|
44
69
|
"notNull": true,
|
|
@@ -46,12 +71,12 @@
|
|
|
46
71
|
"default": "false",
|
|
47
72
|
"generated": null,
|
|
48
73
|
"identity": null,
|
|
49
|
-
"
|
|
50
|
-
"entityType": "columns",
|
|
51
|
-
"schema": "public",
|
|
52
|
-
"table": "todos"
|
|
74
|
+
"entityType": "columns"
|
|
53
75
|
},
|
|
54
76
|
{
|
|
77
|
+
"schema": "public",
|
|
78
|
+
"table": "todos",
|
|
79
|
+
"name": "createdAt",
|
|
55
80
|
"type": "timestamp with time zone",
|
|
56
81
|
"typeSchema": null,
|
|
57
82
|
"notNull": true,
|
|
@@ -59,21 +84,17 @@
|
|
|
59
84
|
"default": "now()",
|
|
60
85
|
"generated": null,
|
|
61
86
|
"identity": null,
|
|
62
|
-
"
|
|
63
|
-
"entityType": "columns",
|
|
64
|
-
"schema": "public",
|
|
65
|
-
"table": "todos"
|
|
87
|
+
"entityType": "columns"
|
|
66
88
|
},
|
|
67
89
|
{
|
|
90
|
+
"schema": "public",
|
|
91
|
+
"table": "todos",
|
|
92
|
+
"name": "todos_pkey",
|
|
68
93
|
"columns": [
|
|
69
94
|
"id"
|
|
70
95
|
],
|
|
71
96
|
"nameExplicit": false,
|
|
72
|
-
"name": "todos_pkey",
|
|
73
|
-
"schema": "public",
|
|
74
|
-
"table": "todos",
|
|
75
97
|
"entityType": "pks"
|
|
76
98
|
}
|
|
77
|
-
]
|
|
78
|
-
"renames": []
|
|
99
|
+
]
|
|
79
100
|
}
|
package/template/nuxt.config.ts
CHANGED
|
@@ -1,4 +1,14 @@
|
|
|
1
1
|
export default defineNuxtConfig({
|
|
2
2
|
modules: ['@wervt/nuxt'],
|
|
3
|
+
// The link preview anyone sees when a link to this (private) app is shared. Name and icon only
|
|
4
|
+
// until set; see AGENTS.md > Users and sessions.
|
|
5
|
+
// wervt: { preview: { title: '', description: '', image: '/og.png' } },
|
|
6
|
+
// Configuration and secrets, typed by these defaults. Values come from
|
|
7
|
+
// `wervt env <app> --set NUXT_EXAMPLE_SECRET=…` (`public` keys: `NUXT_PUBLIC_*`), locally from
|
|
8
|
+
// `.env`. Only `public` reaches the browser. See AGENTS.md > Configuration and secrets.
|
|
9
|
+
runtimeConfig: {
|
|
10
|
+
exampleSecret: '',
|
|
11
|
+
public: {},
|
|
12
|
+
},
|
|
3
13
|
compatibilityDate: '2026-10-01',
|
|
4
14
|
})
|
package/template/package.json
CHANGED
|
@@ -9,15 +9,15 @@
|
|
|
9
9
|
"postinstall": "nuxt prepare"
|
|
10
10
|
},
|
|
11
11
|
"dependencies": {
|
|
12
|
-
"@wervt/nuxt": "^0.3.
|
|
13
|
-
"drizzle-orm": "1.0.0-rc.
|
|
12
|
+
"@wervt/nuxt": "^0.3.3",
|
|
13
|
+
"drizzle-orm": "1.0.0-rc.5",
|
|
14
14
|
"nuxt": "npm:nuxt-nightly@5x",
|
|
15
15
|
"valibot": "^1.5.0",
|
|
16
16
|
"vue": "^3.5.43"
|
|
17
17
|
},
|
|
18
18
|
"devDependencies": {
|
|
19
|
-
"@wervt/cli": "^0.2.
|
|
20
|
-
"drizzle-kit": "1.0.0-rc.
|
|
19
|
+
"@wervt/cli": "^0.2.15",
|
|
20
|
+
"drizzle-kit": "1.0.0-rc.5",
|
|
21
21
|
"vite-plus": "^1.0.0"
|
|
22
22
|
}
|
|
23
23
|
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { defineEventHandler, useRuntimeConfig } from 'nuxt/server'
|
|
2
|
+
|
|
3
|
+
// How server code reads `runtimeConfig` (see nuxt.config.ts). Replace it with a route that needs
|
|
4
|
+
// a secret, e.g. an API key for `$fetch`. Never return the secret itself.
|
|
5
|
+
export default defineEventHandler(() => {
|
|
6
|
+
const { exampleSecret } = useRuntimeConfig()
|
|
7
|
+
return { configured: exampleSecret !== '' }
|
|
8
|
+
})
|