Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

nuxt-app-engineering

/nuxt-app-engineering

Podpowiada, jak budować i wdrażać aplikację webową w Nuxt z Vue 3, TypeScript, Tailwind CSS oraz testami Vitest.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Podpowiada, jak budować i wdrażać aplikację webową w Nuxt z Vue 3, TypeScript, Tailwind CSS oraz testami Vitest.

Oryginalny opis (EN)

Engineering skill: Nuxt web app — how to build and ship a web app with Nuxt on Vue 3, TypeScript, Tailwind CSS, Vitest + @nuxt/test-utils. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code.

Jak działa

  1. Stack
  2. Commands
  3. Structure
  4. Naming
  5. From design and experience skills
  6. Conventions
  7. Do
  8. Don't
  9. Quality gates
  10. Workflow
Sekcje z nagłówków SKILL.md, w oryginale · 179 linii, 2 013 słów
Podgląd SKILL.md
---
name: nuxt-app-engineering
description: "Engineering skill: Nuxt web app — how to build and ship a web app with Nuxt on Vue 3, TypeScript, Tailwind CSS, Vitest + @nuxt/test-utils. Use when writing, reviewing, testing or releasing code in this stack, and when turning a Celestial design or experience skill into code."
type: engineering
stack: web-app
core: "1.0"
checked: 2026-10-26
---

# Nuxt web app

A server-rendered Vue 3 app in TypeScript, with typed server routes in the same project and data fetched once on the server and reused on the client.

For content-rich products and signed-in apps that want server rendering without a separate backend: storefronts, portals, dashboards. Pages render on the Nitro server and hydrate in the browser; the same build deploys to a Node server, serverless functions or static hosting through a preset. Design-skill tokens become a Tailwind theme backed by CSS variables.

## Stack
- **Language:** TypeScript ^5.6 — Auto-generated types cover pages, server routes and runtime config.
- **Framework:** Nuxt on Vue 3 ^4 · Vue ^3.5 — File-based routing, server rendering and a server layer (Nitro) in one project.
- **Styling:** Tailwind CSS ^4 — Theme generated from design tokens; no hand-written colours in single-file components.
- **State:** Pinia for shared client state; useState for SSR-safe small values Pinia ^3 — Stores serialise from server to client without leaking between requests.
- **Data:** useFetch / useAsyncData calling typed Nitro server routes — Data is fetched during server render and reused on hydration instead of refetched.
- **Build:** Vite (via Nuxt) + Nitro bundled with Nuxt — Fast dev server; Nitro builds the server output for the chosen deploy preset.
- **Hosting:** Node server or serverless preset with preview deploys Node 22 LTS+ — Same code, different preset; every pull request gets a link.
- **Package manager:** pnpm ^10 — Fast, strict installs.
- **Testing:** Vitest + @nuxt/test-utils ^3 — Unit and component tests with the Nuxt runtime and auto-imports available.
- **Testing:** Vue Test Utils ^2 — Mounts single-file components with props, slots and events.
- **Testing:** Playwright ^1.50 — Journey tests against the built server, with the accessibility audit.

## Commands
- dev: `pnpm dev`
- e2e: `pnpm build && pnpm test:e2e`
- lint: `pnpm lint && pnpm nuxi typecheck`
- test: `pnpm test`
- build: `pnpm build`
- install: `pnpm install`

## Structure
- `app/pages/` — File-based routes; one .vue file per page
- `app/components/` — Design-skill components, auto-imported; one folder per component with its test
- `app/composables/` — useX() functions wrapping data fetching and shared logic
- `app/stores/` — Pinia stores, only for client state two or more features share
- `server/api/` — Nitro route handlers; method in the filename (orders.get.ts, orders.post.ts)
- `shared/` — Validation schemas and types used by both app/ and server/
- `app/assets/css/tokens.css` — CSS variables written from the design skill
- `tests/e2e/` — One Playwright spec per experience-skill journey

## Naming
- Files: kebab-case for pages, composables and server routes; PascalCase.vue for components
- Tests: *.test.ts beside the file; tests/e2e/<journey-id>.spec.ts
- Branches: type/short-description, e.g. feat/saved-searches
- Components: PascalCase, named after the design-skill component; folder prefixes become part of the auto-import name

## From design and experience skills
When a Celestial design skill is in use, write its tokens as Tailwind theme in `app/assets/css/tokens.css`, and build its components in `app/components` with the same names and variants. Components read tokens only — no raw colours, sizes or font names.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events `object_action` from its measures.

## Conventions
### Code
- Prefer small, pure functions and explicit types at module boundaries. _(Easier to test, review and change.)_

### Components
- Components read design tokens; no raw hex values, pixel sizes or font names in component code. _(One token change restyles the product.)_
- Use script setup with type-based defineProps and defineEmits; never bind v-html to user content. _(Typed component contracts, and no stored XSS through rich text.)_

### Data
- Analytics events are object_action in snake_case and come from the experience skill’s measures. _(Names stay consistent across teams and tools.)_
- Fetch page data with useFetch or useAsyncData using a stable key; call $fetch directly only inside event handlers. _(Plain $fetch in setup runs on the server and again in the browser.)_
- No module-level mutable state in server code or composables; use useState, Pinia or event context. _(Module state is shared across every request on the server.)_

### Errors
- Every async action has loading, empty, error and success states, matching the experience skill. _(Unhandled states are where users get stuck.)_
- Throw createError with a status in server routes and pages; app/error.vue renders the branded error state. _(Status codes stay correct for crawlers and users get a recoverable screen.)_

### Security
- Secrets never live in the repository; read them from the environment or a secret store. _(A leaked key outlives the commit that removed it.)_
- Validate every input on the server, even when the client already did. _(Clients can be bypassed.)_
- Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. _(Cheap protection against the most common attacks.)_
- Server routes parse bodies and queries with readValidatedBody / getValidatedQuery and a shared schema, then check the session. _(Server routes are public endpoints; the schema in shared/ keeps client and server in agreement.)_
- Secrets live in runtimeConfig (server-only keys); only values under runtimeConfig.public reach the browser. _(Anything public is serialised into every page.)_

### Accessibility
- Use native elements first; add ARIA only when no native element fits. _(Native controls bring keyboard and screen-reader support for free.)_
- Every page sets a unique title with useHead or useSeoMeta, and the layout includes the route announcer. _(Client-side navigation is announced like a full page load.)_

## Do
- Use lazy fetching and the pending/error refs for below-the-fold data
- Keep server-only helpers in server/utils so they are never bundled for the browser
- Generate the journey spec from the experience skill before building the screen

## Don't
- Read window or document during setup without a client-only guard
- Create a Pinia store for data that only one page uses
- Disable SSR for a page to hide a hydration mismatch instead of fixing it

## Quality gates
| Gate | Tool | Threshold | When |
|---|---|---|---|
| Lint and types | ESLint (Nuxt config) + nuxi typecheck (vue-tsc) | 0 errors; 0 hydration-mismatch warnings in the e2e run | Every pull request |
| Unit and component tests | The stack’s test runner | All pass; every design-skill component state covered | Every pull request |
| Journey tests | End-to-end runner | One test per experience-skill journey: happy path + error state | Every pull request |
| Accessibility | Automated audit (axe on web, platform audit on mobile) | WCAG 2.2 AA · no new violations | Every pull request |
| Performance budget | Lab measurement in CI | Web: LCP ≤ 2.5s · INP ≤ 200ms · CLS ≤ 0.1 · ≤ 170KB JS per route. Mobile: cold start ≤ 2s · 60fps scroll | Every pull request |
| Dependency and secret scan | Dependency audit + secret scanner | No high or critical findings; no secrets | Every pull request and nightly |
| Preview deploy | Hosting preview environment | A working preview link on the pull request | Every pull request |

The Accessibility gate checks Celestial accessibility core v1.0 (WCAG 2.2 AA); it can change tool but is never skipped. Automated: A11Y-C1, A11Y-F1, A11Y-I1, A11Y-N1, A11Y-N2, A11Y-S1, A11Y-L2, A11Y-P1 (partly). Manual pass before release: A11Y-K1, A11Y-G1, A11Y-R1, A11Y-M1, A11Y-O1, A11Y-V1, A11Y-E1, A11Y-U1, A11Y-L1 — keyboard-only run, screen reader on each journey step, 200% zoom and 320px width, reduced motion, captions on any media. Requirement IDs come from the design and experience skills this code builds. This layer owns: **A11Y-F1** A visible focus indicator on every interactive element, never hidden behind sticky bars (WCAG 2.4.7, 2.4.11); **A11Y-R1** Text works at 200% zoom, at 320px width, with increased text spacing and in either orientation (WCAG 1.4.4, 1.4.10, 1.4.12, 1.3.4); **A11Y-M1** Motion respects the reduced-motion setting; anything moving for over 5 seconds can be paused; nothing flashes more than 3 times a second (WCAG 2.2.2, 2.3.1, 2.3.3 (AAA, advised)); **A11Y-O1** Tooltips and pop-overs shown on hover or focus can be dismissed, hovered and stay until dismissed (WCAG 1.4.13); **A11Y-I1** Images, icons and charts have text alternatives (empty for decoration); text is never an image (WCAG 1.1.1, 1.4.5); **A11Y-V1** Video and audio have captions, transcripts or audio description; nothing plays sound automatically for over 3 seconds (WCAG 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.4.2); **A11Y-K1** Every action works by keyboard in a logical order, with no keyboard traps; single-key shortcuts can be turned off or remapped (WCAG 2.1.1, 2.1.2, 2.1.4, 2.4.3); **A11Y-G1** Nothing is drag-, gesture- or motion-only: each has a single tap or click alternative, and actions fire on release so they can be cancelled (WCAG 2.5.1, 2.5.2, 2.5.4, 2.5.7); **A11Y-N1** Every page has a clear title, headings, landmarks and a skip link, and can be found more than one way (WCAG 2.4.1, 2.4.2, 2.4.5, 2.4.6); **A11Y-N2** Controls have visible labels and instructions; links say where they go; the accessible name contains the visible label (WCAG 2.4.4, 2.5.3, 3.3.2); **A11Y-S1** Status, results and errors are announced to screen readers (WCAG 4.1.3); **A11Y-E2** Never ask for the same information twice in one flow; personal fields declare their purpose so they can be autofilled (WCAG 3.3.7, 1.3.5); **A11Y-U1** Focusing or changing a field never moves the person somewhere else or submits without warning (WCAG 3.2.1, 3.2.2); **A11Y-W1** Time limits warn first and can be extended (WCAG 2.2.1); **A11Y-L2** The page language, and any passage in another language, is declared in code (WCAG 3.1.1, 3.1.2); **A11Y-P1** Structure, order, names, roles and states are in the code: native elements first, ARIA only following the WAI-ARIA patterns (WCAG 1.3.1, 1.3.2, 4.1.2).

## Workflow
- Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

**Review checklist**
- Correctness: does it do what the issue asks, including edge cases?
- Readability: could a new teammate change it safely?
- Architecture: is it in the right place, with the right boundaries?
- Security: inputs, secrets, permissions, dependencies
- Performance: budgets, queries, bundle size
- Tests fail when the code is broken (flip a condition and re-run)
- One approving review; two for auth, payments or data deletion
- Reviewer checks new server routes for validation and session checks

**Definition of done**
- Acceptance criteria met and demoed on the preview link
- Tests added for new behaviour and every state
- Accessibility and performance gates green
- Analytics events named from the experience skill
- Docs or changelog updated when behaviour changes
- Pages render with JavaScript disabled for their primary content

**Release**
- Small pull requests (aim for under 400 changed lines)
- CI green before review
- Squash-merge to main; main is always deployable
- Every release has a written rollback path
- Merge to main deploys to production behind feature flags
- Upgrade Nuxt minor versions monthly in a dedicated pull request

**Incidents**
- Roll back by redeploying the previous build
- Write a blameless note within 48 hours: what happened, impact, fix, prevention

## Overrides of the engineering core
- Lint and types: Adds a hydration-mismatch check to the core gate — Mismatches are the most common server-rendering bug and slip past the type checker.

## Examples
### Validated server route (`server/api/notes.post.ts`)

```ts
import { NoteInput } from '~~/shared/schemas/note';

export default defineEventHandler(async (event) => {
  const session = await requireUserSession(event);
  const body = await readValidatedBody(event, NoteInput.parse);

  const note = await useDb().notes.create({
    ownerId: session.user.id,
    title: body.title,
    text: body.text,
  });

  setResponseStatus(event, 201);
  return note;
});
```

### Page data with a stable key (`app/pages/notes/index.vue`)

```vue
<script setup lang="ts">
useSeoMeta({ title: 'Your notes' });
const { data: notes, status, error, refresh } = await useFetch('/api/notes', { key: 'notes-list' });
</script>

<template>
  <h1>Your notes</h1>
  <LoadingState v-if="status === 'pending'" />
  <ErrorState v-else-if="error" @retry="refresh" />
  <EmptyState v-else-if="!notes?.length" />
  <NoteList v-else :notes="notes" />
</template>
```

## Further reading
- [Nuxt documentation](https://nuxt.com/docs) — Directory structure, data fetching, server routes and deploy presets.
- [Vue guide](https://vuejs.org/guide/introduction.html) — Composition API, reactivity and single-file component rules.
- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/) — Input validation and XSS guidance for server routes and rich text.
Pliki w paczce (4)
  • AGENTS.md 7 KB
  • README.md 2 KB
  • SKILL.md 13 KB
  • rules/nuxt-app-engineering.mdc 5 KB

Wersje

W bazie nie ma innych skilli o nazwie nuxt-app-engineering.

Migawka bazy z 13.11.2026 · wersja paczki b50e6ef1df4b (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100react-web-app-engineering
    Wspiera pisanie, testowanie i wydawanie aplikacji webowej w React, TypeScript, Tailwind CSS i Vitest.
  • 100nextjs-app-engineering
    Prowadzi budowę i wdrażanie aplikacji Next.js App Router w React, TypeScript, Tailwind CSS i Vitest, także przy przenoszeniu projektu wizualnego na kod.
  • 100nuxtjs-vue-typescript
    Podpowiada dobre praktyki dla aplikacji Nuxt 3 i Vue 3 z TypeScript, Composition API i Tailwind CSS: struktura projektu, composables, typy propsów, trasy serwerowe, wtyczki i Web Vitals.
  • 100frontend-vue
    Wspiera tworzenie aplikacji Vue.js z Nuxt 3, Composition API, Tailwind CSS, Pinia i bibliotekami komponentów jak shadcn-vue.
  • 100frontend-vue
    Wspiera tworzenie aplikacji w Vue.js: Nuxt 3, Composition API w Vue 3, Tailwind CSS, Pinia do zarządzania stanem oraz biblioteki komponentów takie jak shadcn-vue.
  • 100nuxt-ui
    Buduje interfejsy w @nuxt/ui v4: ponad 125 dostępnych komponentów Vue z motywami Tailwind CSS, formularze oraz układy dashboardów, stron dokumentacji i czatów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.