create-wervt 0.0.0-stage → 0.1.0

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 CHANGED
@@ -1,3 +1,3 @@
1
- # Temporary Holding Version
1
+ # create-wervt
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `npm create wervt` will scaffold a new wervt app. Work in progress, nothing usable yet.
package/index.js ADDED
@@ -0,0 +1,103 @@
1
+ #!/usr/bin/env node
2
+ // create-wervt: scaffold a wervt app (Nuxt 5 + @wervt/nuxt + Drizzle + valibot + Vite+).
3
+ import { existsSync } from 'node:fs'
4
+ import { cp, readFile, rename, rm, writeFile } from 'node:fs/promises'
5
+ import { dirname, join, relative, resolve } from 'node:path'
6
+ import * as p from '@clack/prompts'
7
+ import { defineCommand, runMain } from 'citty'
8
+ import { downloadTemplate } from 'giget'
9
+ import { installDependencies } from 'nypm'
10
+
11
+ // templates/app, copied into the package when it's packed (see copy-template.js).
12
+ const BUNDLED_TEMPLATE = new URL('./template', import.meta.url).pathname
13
+ const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
14
+
15
+ /** Root of the wervt repo when running inside it, so apps are created as workspace packages. */
16
+ function findMonorepo(from) {
17
+ for (let dir = resolve(from); ; dir = dirname(dir)) {
18
+ if (
19
+ existsSync(join(dir, 'packages/nuxt/package.json')) &&
20
+ existsSync(join(dir, 'templates/app'))
21
+ )
22
+ return dir
23
+ if (dirname(dir) === dir) return undefined
24
+ }
25
+ }
26
+
27
+ const main = defineCommand({
28
+ meta: { name: 'create-wervt', description: 'Create a new wervt app' },
29
+ args: {
30
+ name: { type: 'positional', required: false, description: 'App name ([a-z0-9-])' },
31
+ template: {
32
+ type: 'string',
33
+ description: 'Template source for giget (default: the bundled one)',
34
+ },
35
+ install: { type: 'boolean', default: true, description: 'Install dependencies' },
36
+ force: { type: 'boolean', default: false, description: 'Overwrite an existing directory' },
37
+ },
38
+ async run({ args }) {
39
+ p.intro('create-wervt')
40
+
41
+ let name = args.name
42
+ if (!name) {
43
+ const answer = await p.text({
44
+ message: 'App name',
45
+ placeholder: 'my-app',
46
+ validate: (value) => (NAME_RE.test(value ?? '') ? undefined : 'Use a-z, 0-9 and dashes'),
47
+ })
48
+ if (p.isCancel(answer)) return p.cancel('Cancelled')
49
+ name = answer
50
+ }
51
+ if (!NAME_RE.test(name)) throw new Error(`Invalid app name "${name}": use a-z, 0-9 and dashes`)
52
+
53
+ const monorepo = findMonorepo(process.cwd())
54
+ const dir = monorepo ? join(monorepo, 'apps', name) : resolve(name)
55
+ if (existsSync(dir) && !args.force)
56
+ throw new Error(`${relative(process.cwd(), dir) || dir} already exists (use --force)`)
57
+
58
+ const spinner = p.spinner()
59
+ spinner.start('Creating app')
60
+ if (args.template) {
61
+ await downloadTemplate(args.template, { dir, force: args.force })
62
+ } else if (monorepo) {
63
+ await cp(join(monorepo, 'templates/app'), dir, { recursive: true, force: args.force })
64
+ } else {
65
+ await cp(BUNDLED_TEMPLATE, dir, { recursive: true, force: args.force })
66
+ await rename(join(dir, '_gitignore'), join(dir, '.gitignore'))
67
+ }
68
+
69
+ const pkgPath = join(dir, 'package.json')
70
+ const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
71
+ pkg.name = name
72
+ if (monorepo) {
73
+ // Inside the wervt repo: use the local module, root Vite+ config and lockfile.
74
+ pkg.dependencies['@wervt/nuxt'] = 'workspace:*'
75
+ delete pkg.devDependencies['vite-plus']
76
+ await rm(join(dir, 'vite.config.ts'), { force: true })
77
+ }
78
+ await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
79
+ spinner.stop(`Created ${relative(process.cwd(), dir) || '.'}`)
80
+
81
+ if (args.install) {
82
+ spinner.start('Installing dependencies')
83
+ await installDependencies({ cwd: monorepo ?? dir, silent: true })
84
+ spinner.stop('Installed dependencies')
85
+ }
86
+
87
+ const cd = relative(process.cwd(), dir)
88
+ p.note(
89
+ [
90
+ cd && `cd ${cd}`,
91
+ !args.install && 'pnpm install',
92
+ 'pnpm dev',
93
+ monorepo && `pnpm app:deploy ${name} # from the repo root`,
94
+ ]
95
+ .filter(Boolean)
96
+ .join('\n'),
97
+ 'Next steps',
98
+ )
99
+ p.outro('Agents: read AGENTS.md before writing code.')
100
+ },
101
+ })
102
+
103
+ void runMain(main)
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "create-wervt",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Create a new wervt app: Nuxt 5, Postgres with Drizzle, live data with Electric.",
5
+ "homepage": "https://wervt.app",
6
+ "license": "MIT",
7
+ "author": "Niki2k1",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/wervt-app/wervt.git",
11
+ "directory": "packages/create-wervt"
12
+ },
13
+ "bin": {
14
+ "create-wervt": "index.js"
15
+ },
16
+ "files": [
17
+ "index.js",
18
+ "template",
19
+ "README.md"
20
+ ],
21
+ "type": "module",
22
+ "dependencies": {
23
+ "@clack/prompts": "^1.8.1",
24
+ "citty": "^0.2.2",
25
+ "giget": "^3.3.1",
26
+ "nypm": "^0.6.10"
27
+ },
28
+ "scripts": {}
6
29
  }
@@ -0,0 +1,117 @@
1
+ # wervt app
2
+
3
+ A Nuxt 5 app hosted on [wervt](https://wervt.app). Each app runs in its own isolate (Deno,
4
+ Supabase Edge Runtime) with its own Postgres schema and live data through Electric.
5
+ `@wervt/nuxt` (in `nuxt.config.ts`) sets all of that up. Don't change the Nitro preset.
6
+
7
+ ## Layout
8
+
9
+ - `app.vue`, `pages/`, `components/`: the Vue app.
10
+ - `server/api/`: API routes. `server/api/shapes/`: live data routes.
11
+ - `server/db/schema.ts`: the Drizzle schema. `drizzle/`: generated migrations. Commit both.
12
+
13
+ ## Server routes
14
+
15
+ Use `defineEventHandler` and friends from `nuxt/server` (never `h3` or `nitro/h3`), and validate
16
+ input with valibot through the helpers in `@wervt/nuxt/server`:
17
+
18
+ ```ts
19
+ import { useValidatedBody, useValidatedParams, vh } from '@wervt/nuxt/server'
20
+ import { createError, defineEventHandler } from 'nuxt/server'
21
+ import * as v from 'valibot'
22
+
23
+ export default defineEventHandler(async (event) => {
24
+ const { id } = await useValidatedParams(event, { id: vh.id })
25
+ const body = await useValidatedBody(event, {
26
+ title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)),
27
+ })
28
+ // …
29
+ })
30
+ ```
31
+
32
+ - `useValidatedBody`, `useValidatedQuery`, `useValidatedParams` take a valibot schema or a plain
33
+ `{ key: schema }` object and return typed data. Invalid input becomes a 400 with the issues.
34
+ `useSafeValidated*` return `{ success, data | issues }` instead of throwing.
35
+ - Query values and route params are strings: coerce them with `vh.id`, `vh.intAsString`,
36
+ `vh.numAsString`, `vh.boolAsString`, `vh.checkboxAsString`.
37
+ - Validate every body, query and param. Use valibot, not zod.
38
+ - Throw `createError({ status: 404, message: '…' })` for errors.
39
+ - Cookies and sessions: `getCookie`, `setCookie`, `useSession` from `nuxt/server`.
40
+ - Nothing is auto-imported on the server: import everything explicitly.
41
+
42
+ ## Database
43
+
44
+ ```ts
45
+ import { useDb } from '@wervt/nuxt/server'
46
+ import { eq } from 'drizzle-orm'
47
+ import { todos } from '../db/schema'
48
+
49
+ const rows = await useDb().select().from(todos).where(eq(todos.done, false))
50
+ ```
51
+
52
+ - Drizzle ORM v1 (`drizzle-orm@1.0.0-rc`) on Postgres. Declare tables with `pgTable` and **no
53
+ schema** (no `pgSchema`): the app's role only sees its own schema.
54
+ - After changing `server/db/schema.ts`, run `pnpm db:generate` and commit the new folder in
55
+ `drizzle/`. Never edit generated migrations. Migrations run on deploy and on `nuxt dev`.
56
+ - Don't read `DATABASE_URL` yourself and don't create other clients. Use `useDb()`.
57
+ - For relational queries (`db.query.rooms.findFirst({ with: … })`), define relations with
58
+ `defineRelations` in `server/db/relations.ts` and use `useDb({ relations })`.
59
+ - No raw SQL against other schemas, `public`, or system catalogs: the role can't access them.
60
+
61
+ ## Live data
62
+
63
+ Prefer live data over refetching. A shape is one table, optionally filtered:
64
+
65
+ ```ts
66
+ // server/api/shapes/todos.get.ts
67
+ import { proxyShape } from '@wervt/nuxt/server'
68
+ import { defineEventHandler } from 'nuxt/server'
69
+
70
+ export default defineEventHandler((event) => proxyShape(event, { table: 'todos' }))
71
+ ```
72
+
73
+ ```vue
74
+ <script setup lang="ts">
75
+ const { data: todos, isLive } = await useShape<Todo>('/api/shapes/todos')
76
+ </script>
77
+ ```
78
+
79
+ - `useShape` is auto-imported. It loads rows during SSR and keeps them live; writes made through
80
+ any API route show up in every open tab without refetching.
81
+ - Writes go through normal API routes (`$fetch('/api/todos', { method: 'POST', body })`).
82
+ - Shapes can't join. Load several shapes and combine them with `computed`.
83
+ - Shape rows are JSON: timestamps arrive as Postgres text (`2026-10-06 01:02:03.123+00`), not
84
+ `Date`. Column names are what the client sees, so keep them camelCase like the schema keys.
85
+ - Never put secrets in a shape: list the `columns` a client may see.
86
+ - Do auth checks in the shape route and restrict rows with `where`. Pass values as `params`,
87
+ never by building the SQL string:
88
+
89
+ ```ts
90
+ proxyShape(event, { table: 'notes', where: '"ownerId" = $1', params: [userId] })
91
+ ```
92
+
93
+ ## Users and sessions
94
+
95
+ - `useWervtUser(event)` (server, from `@wervt/nuxt/server`) and `useWervtUser()` (app,
96
+ auto-imported) give the signed-in wervt user or nothing. Private apps always have one; public
97
+ 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
98
+ external links. Never build your own login or OAuth.
99
+ - For your own state (anonymous visitors too), use `useSession(event, { name })` from
100
+ `nuxt/server`. The secret is set by wervt.
101
+
102
+ ## Don'ts
103
+
104
+ - No Node-only APIs that Deno lacks (`child_process`, native addons, writing to the filesystem).
105
+ Store data in Postgres.
106
+ - No long-running work in requests (CPU is limited per request) and no in-memory state that must
107
+ survive: isolates are started and stopped on demand.
108
+ - No WebSockets, SSE hubs or timers that push to clients. Write to the database and let clients
109
+ read live data through shapes. No background jobs or cron either: do periodic cleanup lazily in
110
+ requests.
111
+ - No secrets in client code. Server env vars come from wervt; don't hardcode credentials.
112
+
113
+ ## Commands
114
+
115
+ - `pnpm dev`: dev server against the local wervt stack (`docker compose up -d` in the wervt repo).
116
+ - `pnpm db:generate`: generate a migration from the schema.
117
+ - `pnpm exec vp check --fix`: format, lint and type check. Run it before finishing.
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,5 @@
1
+ node_modules
2
+ .nuxt
3
+ .output
4
+ .data
5
+ .env
@@ -0,0 +1,37 @@
1
+ <script setup lang="ts">
2
+ import type { Todo } from './server/db/schema'
3
+
4
+ // Rows arrive with SSR and then stay live: every write below shows up here (and in every
5
+ // other open tab) through Electric, so there is nothing to refetch.
6
+ const { data, isLive } = await useShape<Todo>('/api/shapes/todos')
7
+ const todos = computed(() => data.value.toSorted((a, b) => a.id - b.id))
8
+ const title = ref('')
9
+
10
+ async function add() {
11
+ await $fetch('/api/todos', { method: 'POST', body: { title: title.value } })
12
+ title.value = ''
13
+ }
14
+ const toggle = (todo: Todo) =>
15
+ $fetch(`/api/todos/${todo.id}`, { method: 'PATCH', body: { done: !todo.done } })
16
+ const remove = (todo: Todo) => $fetch(`/api/todos/${todo.id}`, { method: 'DELETE' })
17
+ </script>
18
+
19
+ <template>
20
+ <main>
21
+ <h1>Todos</h1>
22
+ <p>{{ isLive ? 'Live' : 'Connecting…' }}</p>
23
+ <form @submit.prevent="add">
24
+ <input v-model="title" placeholder="What needs doing?" required />
25
+ <button>Add</button>
26
+ </form>
27
+ <ul>
28
+ <li v-for="todo in todos" :key="todo.id">
29
+ <label>
30
+ <input type="checkbox" :checked="todo.done" @change="toggle(todo)" />
31
+ {{ todo.title }}
32
+ </label>
33
+ <button @click="remove(todo)">Delete</button>
34
+ </li>
35
+ </ul>
36
+ </main>
37
+ </template>
@@ -0,0 +1,6 @@
1
+ CREATE TABLE "todos" (
2
+ "id" serial PRIMARY KEY,
3
+ "title" text NOT NULL,
4
+ "done" boolean DEFAULT false NOT NULL,
5
+ "createdAt" timestamp with time zone DEFAULT now() NOT NULL
6
+ );
@@ -0,0 +1,79 @@
1
+ {
2
+ "version": "8",
3
+ "dialect": "postgres",
4
+ "id": "89541799-b7fd-4ea4-bc66-6c6a95f8abf6",
5
+ "prevIds": [
6
+ "00000000-0000-0000-0000-000000000000"
7
+ ],
8
+ "ddl": [
9
+ {
10
+ "isRlsEnabled": false,
11
+ "name": "todos",
12
+ "entityType": "tables",
13
+ "schema": "public"
14
+ },
15
+ {
16
+ "type": "serial",
17
+ "typeSchema": null,
18
+ "notNull": true,
19
+ "dimensions": 0,
20
+ "default": null,
21
+ "generated": null,
22
+ "identity": null,
23
+ "name": "id",
24
+ "entityType": "columns",
25
+ "schema": "public",
26
+ "table": "todos"
27
+ },
28
+ {
29
+ "type": "text",
30
+ "typeSchema": null,
31
+ "notNull": true,
32
+ "dimensions": 0,
33
+ "default": null,
34
+ "generated": null,
35
+ "identity": null,
36
+ "name": "title",
37
+ "entityType": "columns",
38
+ "schema": "public",
39
+ "table": "todos"
40
+ },
41
+ {
42
+ "type": "boolean",
43
+ "typeSchema": null,
44
+ "notNull": true,
45
+ "dimensions": 0,
46
+ "default": "false",
47
+ "generated": null,
48
+ "identity": null,
49
+ "name": "done",
50
+ "entityType": "columns",
51
+ "schema": "public",
52
+ "table": "todos"
53
+ },
54
+ {
55
+ "type": "timestamp with time zone",
56
+ "typeSchema": null,
57
+ "notNull": true,
58
+ "dimensions": 0,
59
+ "default": "now()",
60
+ "generated": null,
61
+ "identity": null,
62
+ "name": "createdAt",
63
+ "entityType": "columns",
64
+ "schema": "public",
65
+ "table": "todos"
66
+ },
67
+ {
68
+ "columns": [
69
+ "id"
70
+ ],
71
+ "nameExplicit": false,
72
+ "name": "todos_pkey",
73
+ "schema": "public",
74
+ "table": "todos",
75
+ "entityType": "pks"
76
+ }
77
+ ],
78
+ "renames": []
79
+ }
@@ -0,0 +1,7 @@
1
+ import { defineConfig } from 'drizzle-kit'
2
+
3
+ export default defineConfig({
4
+ dialect: 'postgresql',
5
+ schema: './server/db/schema.ts',
6
+ out: './drizzle',
7
+ })
@@ -0,0 +1,4 @@
1
+ export default defineNuxtConfig({
2
+ modules: ['@wervt/nuxt'],
3
+ compatibilityDate: '2026-10-01',
4
+ })
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "wervt-app",
3
+ "private": true,
4
+ "type": "module",
5
+ "scripts": {
6
+ "dev": "nuxt dev",
7
+ "build": "nuxt build",
8
+ "db:generate": "drizzle-kit generate",
9
+ "postinstall": "nuxt prepare"
10
+ },
11
+ "dependencies": {
12
+ "@wervt/nuxt": "^0.1.0",
13
+ "drizzle-orm": "1.0.0-rc.4",
14
+ "nuxt": "npm:nuxt-nightly@5x",
15
+ "valibot": "^1.5.0"
16
+ },
17
+ "devDependencies": {
18
+ "drizzle-kit": "1.0.0-rc.4",
19
+ "vite-plus": "^1.0.0"
20
+ }
21
+ }
@@ -0,0 +1,6 @@
1
+ import { proxyShape } from '@wervt/nuxt/server'
2
+ import { defineEventHandler } from 'nuxt/server'
3
+
4
+ // Live data for useShape('/api/shapes/todos'). Check auth here and narrow rows with
5
+ // `where` before exposing anything user-specific.
6
+ export default defineEventHandler((event) => proxyShape(event, { table: 'todos' }))
@@ -0,0 +1,10 @@
1
+ import { useDb, useValidatedParams, vh } from '@wervt/nuxt/server'
2
+ import { eq } from 'drizzle-orm'
3
+ import { defineEventHandler, setResponseStatus } from 'nuxt/server'
4
+ import { todos } from '../../db/schema'
5
+
6
+ export default defineEventHandler(async (event) => {
7
+ const { id } = await useValidatedParams(event, { id: vh.id })
8
+ await useDb().delete(todos).where(eq(todos.id, id))
9
+ setResponseStatus(event, 204)
10
+ })
@@ -0,0 +1,16 @@
1
+ import { useDb, useValidatedBody, useValidatedParams, vh } from '@wervt/nuxt/server'
2
+ import { eq } from 'drizzle-orm'
3
+ import { createError, defineEventHandler } from 'nuxt/server'
4
+ import * as v from 'valibot'
5
+ import { todos } from '../../db/schema'
6
+
7
+ export default defineEventHandler(async (event) => {
8
+ const { id } = await useValidatedParams(event, { id: vh.id })
9
+ const values = await useValidatedBody(event, {
10
+ title: v.optional(v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200))),
11
+ done: v.optional(v.boolean()),
12
+ })
13
+ const [todo] = await useDb().update(todos).set(values).where(eq(todos.id, id)).returning()
14
+ if (!todo) throw createError({ status: 404, message: 'Todo not found' })
15
+ return todo
16
+ })
@@ -0,0 +1,12 @@
1
+ import { useDb, useValidatedBody } from '@wervt/nuxt/server'
2
+ import { defineEventHandler } from 'nuxt/server'
3
+ import * as v from 'valibot'
4
+ import { todos } from '../db/schema'
5
+
6
+ export default defineEventHandler(async (event) => {
7
+ const values = await useValidatedBody(event, {
8
+ title: v.pipe(v.string(), v.trim(), v.nonEmpty(), v.maxLength(200)),
9
+ })
10
+ const [todo] = await useDb().insert(todos).values(values).returning()
11
+ return todo
12
+ })
@@ -0,0 +1,12 @@
1
+ import { boolean, pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core'
2
+
3
+ // Tables are declared without a schema: on wervt the app's database role only sees
4
+ // its own schema. Run `pnpm db:generate` after changing this file.
5
+ export const todos = pgTable('todos', {
6
+ id: serial().primaryKey(),
7
+ title: text().notNull(),
8
+ done: boolean().notNull().default(false),
9
+ createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
10
+ })
11
+
12
+ export type Todo = typeof todos.$inferSelect
@@ -0,0 +1,9 @@
1
+ {
2
+ "files": [],
3
+ "references": [
4
+ { "path": "./.nuxt/tsconfig.app.json" },
5
+ { "path": "./.nuxt/tsconfig.server.json" },
6
+ { "path": "./.nuxt/tsconfig.shared.json" },
7
+ { "path": "./.nuxt/tsconfig.node.json" }
8
+ ]
9
+ }
@@ -0,0 +1,13 @@
1
+ import { defineConfig } from 'vite-plus'
2
+
3
+ export default defineConfig({
4
+ fmt: {
5
+ singleQuote: true,
6
+ semi: false,
7
+ printWidth: 100,
8
+ ignorePatterns: ['drizzle/**'],
9
+ },
10
+ lint: {
11
+ options: { typeAware: true, typeCheck: true },
12
+ },
13
+ })