create-wervt 0.2.15 → 0.2.16

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.
Files changed (32) hide show
  1. package/index.js +2 -0
  2. package/package.json +2 -2
  3. package/template/.claude/skills/nuxt-ui/SKILL.md +85 -243
  4. package/template/.claude/skills/nuxt-ui/references/components.md +184 -313
  5. package/template/.claude/skills/nuxt-ui/references/guidelines/component-selection.md +124 -0
  6. package/template/.claude/skills/nuxt-ui/references/guidelines/conventions.md +372 -0
  7. package/template/.claude/skills/nuxt-ui/references/guidelines/design-system.md +378 -0
  8. package/template/.claude/skills/nuxt-ui/references/guidelines/forms.md +235 -0
  9. package/template/.claude/skills/nuxt-ui/references/layouts/chat.md +140 -77
  10. package/template/.claude/skills/nuxt-ui/references/layouts/dashboard.md +33 -19
  11. package/template/.claude/skills/nuxt-ui/references/layouts/docs.md +23 -12
  12. package/template/.claude/skills/nuxt-ui/references/layouts/editor.md +49 -63
  13. package/template/.claude/skills/nuxt-ui/references/layouts/{page.md → landing.md} +43 -118
  14. package/template/.claude/skills/nuxt-ui/references/recipes/auth.md +162 -0
  15. package/template/.claude/skills/nuxt-ui/references/recipes/data-tables.md +249 -0
  16. package/template/.claude/skills/nuxt-ui/references/recipes/navigation.md +90 -0
  17. package/template/.claude/skills/nuxt-ui/references/recipes/overlays.md +177 -0
  18. package/template/.claude/skills/nuxt-ui-mobile/SKILL.md +38 -10
  19. package/template/.claude/skills/nuxt-ui-mobile/references/identity.md +127 -0
  20. package/template/.claude/skills/nuxt-ui-mobile/references/patterns.md +1 -0
  21. package/template/.claude/skills/nuxt-ui-mobile/references/review-checklist.md +14 -6
  22. package/template/.claude/skills/nuxt-ui-mobile/references/tokens.md +1 -1
  23. package/template/.claude/skills/nuxt-ui-mobile/template/app/assets/css/main.css +9 -9
  24. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ListSection.vue +7 -3
  25. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/NavBar.vue +13 -4
  26. package/template/.claude/skills/nuxt-ui-mobile/template/nuxt.config.ts +2 -1
  27. package/template/AGENTS.md +114 -8
  28. package/template/golar.config.ts +5 -0
  29. package/template/package.json +7 -4
  30. package/template/pnpm-workspace.yaml +2 -0
  31. package/template/.claude/skills/nuxt-ui/references/composables.md +0 -127
  32. package/template/.claude/skills/nuxt-ui/references/theming.md +0 -427
@@ -29,17 +29,23 @@ onMounted(() => {
29
29
  })
30
30
  onBeforeUnmount(() => window.removeEventListener('scroll', update))
31
31
 
32
+ // Back must not push: pushing the parent puts it on top of the child, and the next back from
33
+ // the parent lands on the child again.
32
34
  function goBack() {
33
- if (typeof props.back === 'string') return router.push(props.back)
34
- if (window.history.state?.back) return router.back()
35
- router.push('/')
35
+ const previous = window.history.state?.back
36
+ if (typeof props.back === 'string') {
37
+ if (previous === props.back) return router.back()
38
+ return router.replace(props.back)
39
+ }
40
+ if (previous) return router.back()
41
+ router.replace('/')
36
42
  }
37
43
  </script>
38
44
 
39
45
  <template>
40
46
  <header
41
47
  ref="bar"
42
- class="sticky top-0 z-30 pt-safe transition-[background-color,box-shadow] duration-200 select-none"
48
+ class="sticky top-0 z-30 pt-[max(env(safe-area-inset-top),0.5rem)] pb-2 transition-[background-color,box-shadow] duration-200 select-none"
43
49
  :class="scrolled && collapsed ? 'glass-bar shadow-[0_0.5px_0_var(--ui-border)]' : 'bg-transparent'"
44
50
  >
45
51
  <div class="grid h-(--ui-header-height) grid-cols-[1fr_auto_1fr] items-center gap-2 px-4">
@@ -81,6 +87,9 @@ function goBack() {
81
87
  <h1 v-else class="sr-only">
82
88
  {{ title }}
83
89
  </h1>
90
+ <!-- Without a large title nothing separates the bar from the content. After the v-if/v-else
91
+ pair: in between it would break the chain. -->
92
+ <div v-if="!large" class="h-1" aria-hidden="true" />
84
93
 
85
94
  <div v-if="$slots.default" class="px-4 pb-2">
86
95
  <slot />
@@ -3,7 +3,8 @@ export default defineNuxtConfig({
3
3
 
4
4
  css: ['~/assets/css/main.css'],
5
5
 
6
- // System font stack only — no web-font download
6
+ // System font by default. Set to true when the app uses a display font (references/identity.md):
7
+ // @nuxt/fonts then downloads and self-hosts it.
7
8
  ui: {
8
9
  fonts: false
9
10
  },
@@ -24,8 +24,10 @@ Pick the UI stack by the kind of app:
24
24
  their own identity): Reka UI (`reka-ui`) for accessible behavior (dialogs, menus, popovers,
25
25
  sliders, …) and Tailwind CSS with your own styles on top. Don't bend Nuxt UI's theme into a
26
26
  different design.
27
- - **Pure mobile apps** (used mainly on phones, should feel like a native iOS app): Nuxt UI with the
28
- `nuxt-ui-mobile` skill. Read its `SKILL.md` before writing UI and follow its rules. Its
27
+ - **Pure mobile apps** (used mainly on phones, should feel like a real app from the App Store):
28
+ Nuxt UI with the `nuxt-ui-mobile` skill: iOS mechanics plus an own look per app (brand color,
29
+ imagery, a home screen with the person's content). Read its `SKILL.md` and decide the app's
30
+ identity before writing UI, then follow its rules. Its
29
31
  `template/app/*` files go to the project root here: this app keeps `app.vue`, `pages/` and
30
32
  `components/` at the root, not in `app/`.
31
33
 
@@ -37,6 +39,9 @@ UI's own icons are Lucide), plus `@iconify-json/<name>` for each other prefix yo
37
39
  @nuxt/icon bundles the locally installed collections into the server by itself; `@wervt/nuxt` only
38
40
  stops the server from falling back to the API and warns on build when Lucide is missing (the full
39
41
  `@iconify/json` package counts too).
42
+ Icons that only show up after the page loaded (client-only parts, `v-if` on fetched data) need
43
+ their data in the client bundle too: `icon: { clientBundle: { scan: true } }` in `nuxt.config.ts`.
44
+ Otherwise they render empty in the browser while the server-rendered ones look fine.
40
45
 
41
46
  OG images (`defineOgImage`): `pnpm add nuxt-og-image @takumi-rs/core @takumi-rs/wasm`. The isolate
42
47
  can't load native renderers, so `@wervt/nuxt` switches nuxt-og-image to WebAssembly; don't set
@@ -120,8 +125,9 @@ Example and fixture data goes into the `db:seed` task in `server/tasks/db/seed.t
120
125
  migrations. Keep it idempotent: `seedTable(table, rows)` from `@wervt/nuxt/server` only inserts
121
126
  while the table is empty.
122
127
 
123
- - `nuxt dev` runs it once, right after it created and migrated a new local database.
124
- `pnpm exec nuxt task run db:seed` runs it again while the dev server is running.
128
+ - `nuxt dev` runs it once, right after it created and migrated a new local database. Tables you
129
+ add to an existing database stay empty: after `pnpm db:generate`, wait for the dev server to
130
+ migrate, then `pnpm exec nuxt task run db:seed`.
125
131
  - It's never scheduled and never runs on deploy. Seed production only when asked:
126
132
  `pnpm exec wervt tasks <app> --run db:seed`.
127
133
  - Update the seed when the schema changes, so a new database still seeds.
@@ -210,6 +216,101 @@ own bucket and `@wervt/nuxt` connects it; don't configure a provider or S3 crede
210
216
  - No tus uploads and no `transform` / sharp: they need a disk and native modules.
211
217
  - Check access in the route before serving a file.
212
218
 
219
+ ## Real-world things
220
+
221
+ When the app is about things that exist (films, series, books, places, dishes, plants, people,
222
+ brands), show real ones with real pictures instead of made-up entries, and let people find them
223
+ by typing. Wikipedia covers most of that, in every language, with no key: a search returns the
224
+ title, a one-sentence description and the lead image. Covers of films and albums are only on the
225
+ English Wikipedia, so the route falls back to it for pictures.
226
+
227
+ ```ts
228
+ // server/api/lookup.get.ts
229
+ import { useValidatedQuery } from '@wervt/nuxt/server'
230
+ import { defineEventHandler } from 'nuxt/server'
231
+ import * as v from 'valibot'
232
+
233
+ type Page = {
234
+ title: string
235
+ index: number
236
+ fullurl: string
237
+ extract?: string
238
+ thumbnail?: { source: string }
239
+ langlinks?: { title: string }[]
240
+ }
241
+
242
+ // Wikimedia asks every client to name itself.
243
+ const AGENT = 'wervt-app (https://wervt.app)'
244
+
245
+ async function wiki(lang: string, params: Record<string, string>) {
246
+ const url = new URL(`https://${lang}.wikipedia.org/w/api.php`)
247
+ const query = { action: 'query', format: 'json', formatversion: '2', ...params }
248
+ for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value)
249
+ const res = await fetch(url, { headers: { 'user-agent': AGENT } })
250
+ if (!res.ok) return []
251
+ return ((await res.json()) as { query?: { pages?: Page[] } }).query?.pages ?? []
252
+ }
253
+
254
+ export default defineEventHandler(async (event) => {
255
+ const { q } = await useValidatedQuery(event, {
256
+ q: v.pipe(v.string(), v.trim(), v.minLength(2), v.maxLength(100)),
257
+ })
258
+ const lang: string = 'de' // the app's language
259
+ const pages = (
260
+ await wiki(lang, {
261
+ // Adding the kind (`${q} Film`) keeps a film app from finding the physicist first.
262
+ generator: 'search',
263
+ gsrsearch: q,
264
+ gsrlimit: '6',
265
+ prop: 'pageimages|extracts|langlinks|info',
266
+ inprop: 'url',
267
+ piprop: 'thumbnail',
268
+ pithumbsize: '400',
269
+ pilicense: 'any',
270
+ exintro: '1',
271
+ explaintext: '1',
272
+ exsentences: '1',
273
+ exlimit: '6',
274
+ lllang: 'en',
275
+ lllimit: '6',
276
+ })
277
+ ).sort((a, b) => a.index - b.index)
278
+
279
+ const english = pages.flatMap((p) =>
280
+ !p.thumbnail && p.langlinks?.[0] ? [p.langlinks[0].title] : [],
281
+ )
282
+ const covers = new Map<string, string>()
283
+ if (english.length && lang !== 'en') {
284
+ const params = {
285
+ titles: english.join('|'),
286
+ prop: 'pageimages',
287
+ piprop: 'thumbnail',
288
+ pithumbsize: '400',
289
+ pilicense: 'any',
290
+ }
291
+ for (const page of await wiki('en', params))
292
+ if (page.thumbnail) covers.set(page.title, page.thumbnail.source)
293
+ }
294
+ return pages.map((p) => ({
295
+ title: p.title,
296
+ description: p.extract,
297
+ image: p.thumbnail?.source ?? covers.get(p.langlinks?.[0]?.title ?? ''),
298
+ url: p.fullurl,
299
+ }))
300
+ })
301
+ ```
302
+
303
+ - On the page: `UInputMenu` with `v-model:search-term`, `ignore-filter`, items from the route
304
+ (debounced, `refDebounced`), each with `avatar: { src: image }` and the description as a second
305
+ line. Picking one fills the form; typing something Wikipedia doesn't know still works.
306
+ - Save `title`, `image` and `url` with the entry, so lists don't ask Wikipedia again. Show the
307
+ image straight from Wikimedia (`<img :src loading="lazy">`), with a colored placeholder when
308
+ there is none.
309
+ - Example content (seed) uses the same route's results: real things with their pictures.
310
+ - Pictures from Wikipedia aren't yours: name the source in a small "Bilder: Wikipedia" line on an
311
+ about or settings screen. Film posters there are non-free; fine for a prototype, not for a
312
+ product, which needs a licensed source (TMDB and the like).
313
+
213
314
  ## Tasks (cron)
214
315
 
215
316
  Periodic work (cleanup, syncs, renewals) goes into tasks, not into requests:
@@ -353,11 +454,16 @@ Queries are LogsQL. Logs may contain user data: quote only what's needed.
353
454
 
354
455
  ## Commands
355
456
 
356
- - `pnpm dev`: dev server. Pages and API routes work on their own; the database, live data and
357
- files need the local wervt stack (`docker compose up -d` in the wervt repo), which is optional.
358
- Without it, check database work on the deployed app.
457
+ - `pnpm dev`: dev server. Pages and API routes work on their own; the database and live data need
458
+ the local wervt stack (`docker compose up -d postgres electric` in the wervt repo, plus `garage`
459
+ for files), which is optional. Without it, check database work on the deployed app. If a new
460
+ composable or util is "not defined" in the running dev server, restart it: Nuxt 5's nightly
461
+ sometimes misses files added while it runs.
359
462
  - `pnpm db:generate`: generate a migration from the schema.
360
- - `pnpm exec vp check --fix`: format, lint and type check. Run it before finishing.
463
+ - `pnpm exec vp check --fix`: format, lint and type check the TypeScript. It reformats files, so
464
+ read a file again before editing it afterwards.
465
+ - `pnpm typecheck`: type check everything, `.vue` files included (Golar). Run it and
466
+ `vp check --fix` before finishing.
361
467
  - Deploys: pushing to `main` deploys through `.github/workflows/deploy.yml`.
362
468
  `pnpm exec wervt releases <app>` lists releases with their commits. Don't deploy, roll back or
363
469
  create deploy tokens unless asked.
@@ -0,0 +1,5 @@
1
+ // `pnpm typecheck` checks .vue files with Golar; `vp check` doesn't see into them.
2
+ import { defineConfig } from 'golar/unstable'
3
+ import '@golar/vue'
4
+
5
+ export default defineConfig({})
@@ -5,19 +5,22 @@
5
5
  "scripts": {
6
6
  "dev": "nuxt dev",
7
7
  "build": "nuxt build",
8
+ "typecheck": "nuxt typecheck",
8
9
  "db:generate": "drizzle-kit generate",
9
10
  "postinstall": "nuxt prepare"
10
11
  },
11
12
  "dependencies": {
12
- "@wervt/nuxt": "^0.3.3",
13
+ "@wervt/nuxt": "^0.3.4",
13
14
  "drizzle-orm": "1.0.0-rc.5",
14
15
  "nuxt": "npm:nuxt-nightly@5x",
15
16
  "valibot": "^1.5.0",
16
- "vue": "^3.5.43"
17
+ "vue": "^3.5.44"
17
18
  },
18
19
  "devDependencies": {
19
- "@wervt/cli": "^0.2.15",
20
+ "@golar/vue": "^0.1.11",
21
+ "@wervt/cli": "^0.2.16",
20
22
  "drizzle-kit": "1.0.0-rc.5",
21
- "vite-plus": "^1.0.0"
23
+ "golar": "^0.1.11",
24
+ "vite-plus": "^1.3.0"
22
25
  }
23
26
  }
@@ -1,6 +1,8 @@
1
1
  # pnpm only runs install scripts it has been told about; esbuild is the one this app needs.
2
2
  allowBuilds:
3
3
  esbuild: true
4
+ # Nuxt UI pulls it in; its install script only matters for Vue 2.
5
+ vue-demi: false
4
6
  minimumReleaseAgeExclude:
5
7
  # wervt's own packages, so a new app gets the release that was just published.
6
8
  - '@wervt/*'
@@ -1,127 +0,0 @@
1
- # Composables
2
-
3
- ## useToast
4
-
5
- Show notifications. Requires `<UApp>` wrapper.
6
-
7
- ```ts
8
- const toast = useToast()
9
-
10
- toast.add({
11
- title: 'Success',
12
- description: 'Item saved',
13
- color: 'success', // primary, success, error, warning, info
14
- icon: 'i-lucide-check-circle',
15
- duration: 5000, // 0 = never dismiss
16
- actions: [{ label: 'Undo', onClick: () => {} }]
17
- })
18
-
19
- toast.remove('toast-id')
20
- toast.clear()
21
- ```
22
-
23
- ## useOverlay
24
-
25
- Programmatically create modals, slideovers, drawers.
26
-
27
- ```ts
28
- const overlay = useOverlay()
29
-
30
- // create() returns a reusable instance with open(), close(), patch()
31
- const modal = overlay.create(MyComponent)
32
-
33
- // open() accepts props and returns an object with .result (a Promise)
34
- const { result } = modal.open({ title: 'Confirm' })
35
-
36
- if (await result) {
37
- // User confirmed
38
- }
39
-
40
- // Inside the overlay component, emit close with a value:
41
- // emit('close', true) or emit('close', false)
42
-
43
- // You can also close from outside:
44
- modal.close(false)
45
- ```
46
-
47
- ## defineShortcuts
48
-
49
- Define keyboard shortcuts.
50
-
51
- ```ts
52
- defineShortcuts({
53
- meta_k: () => openSearch(), // Cmd+K (Mac) / Ctrl+K (Win)
54
- meta_shift_p: () => openPalette(), // Cmd+Shift+P
55
- escape: () => close(),
56
- ctrl_s: () => save(),
57
-
58
- // With condition
59
- meta_enter: {
60
- handler: () => submit(),
61
- whenever: [isFormValid]
62
- }
63
- })
64
- ```
65
-
66
- | Key | Meaning |
67
- |---|---|
68
- | `meta` | Cmd (Mac) / Ctrl (Windows) |
69
- | `ctrl` | Ctrl key |
70
- | `alt` | Alt / Option key |
71
- | `shift` | Shift key |
72
- | `_` | Key separator |
73
-
74
- ## defineLocale / extendLocale
75
-
76
- i18n locale definition.
77
-
78
- ```ts
79
- import { fr } from '@nuxt/ui/locale'
80
-
81
- // Use a built-in locale (50+ available)
82
- // <UApp :locale="fr">
83
-
84
- // Define custom locale
85
- const locale = defineLocale({
86
- name: 'Español',
87
- code: 'es',
88
- dir: 'ltr',
89
- messages: {
90
- select: { placeholder: 'Seleccionar...' }
91
- }
92
- })
93
-
94
- // Extend existing locale
95
- import { en } from '@nuxt/ui/locale'
96
-
97
- const customEn = extendLocale(en, {
98
- messages: { commandPalette: { placeholder: 'Search a component...' } }
99
- })
100
- ```
101
-
102
- ```vue
103
- <UApp :locale="fr"><NuxtPage /></UApp>
104
- ```
105
-
106
- ## extractShortcuts
107
-
108
- Extract shortcut keys from a list of items (e.g., dropdown menu items) into a shortcuts map for `defineShortcuts`.
109
-
110
- ```ts
111
- const items = [
112
- { label: 'New file', kbds: ['meta', 'n'], onSelect: () => newFile() },
113
- { label: 'Save', kbds: ['meta', 's'], onSelect: () => save() }
114
- ]
115
-
116
- defineShortcuts(extractShortcuts(items))
117
- ```
118
-
119
- ## Quick reference
120
-
121
- | Composable | Purpose |
122
- |---|---|
123
- | `useToast` | Show notifications |
124
- | `useOverlay` | Programmatic modals/slideovers |
125
- | `defineShortcuts` | Keyboard shortcuts |
126
- | `defineLocale` / `extendLocale` | i18n locale |
127
- | `extractShortcuts` | Parse shortcut definitions |