Przepisy rozwoju Nuxt 3

Nuxt 3 daje ci routing oparty na plikach, auto-importy, trasy serwera i renderowanie hybrydowe od razu po instalacji. Te przepisy pomagają ci używać narzędzi AI do budowania na tym fundamencie bez walki z konwencjami frameworka. Każdy prompt tutaj generuje kod, który respektuje strukturę katalogów Nuxt, wykorzystuje auto-importy i poprawnie obsługuje granice SSR/CSR.

Co wyniesiesz z tego rozdziału

Przepisy na trasy serwera obsługujące uwierzytelnianie, walidację i dostęp do bazy danych
Wzorce composables do pobierania danych z useFetch i useAsyncData
Przepisy na middleware i pluginy do strażników auth i globalnego stanu
Prompty wdrożeniowe dla Vercel, Cloudflare i Netlify edge

Przepis 1: Trasa API serwera z walidacją Zod

Scenariusz: Potrzebujesz endpointu POST do tworzenia postów na blogu z walidacją Zod, sprawdzaniem uwierzytelniania i poprawnymi odpowiedziami błędów.

Utwórz trasę serwera Nuxt w server/api/posts.post.ts. Użyj defineEventHandler z readValidatedBody i schematem Zod do walidacji. Schemat powinien wymagać title (string, 3-200 znaków), content (string, min 10 znaków), categoryId (UUID string), tags (tablica stringów, max 5) i publishedAt (opcjonalny ISO date string). Sprawdź nagłówek Authorization szukając tokena Bearer, zweryfikuj go używając verifyJWT() z server/utils/auth.ts. Jeśli nieprawidłowy, rzuć createError({ statusCode: 401, message: 'Unauthorized' }). Przy prawidłowym żądaniu wstaw do bazy danych używając Drizzle ORM, zwróć utworzony post ze statusem 201. Obsłuż duplikat tytułu odpowiedzią 409 Conflict. Napisz towarzyszący test używając $fetch z @nuxt/test-utils, który obejmuje prawidłowe tworzenie, błędy walidacji, błąd uwierzytelniania i duplikat tytułu.

Oczekiwane wyjście: Plik trasy serwera, schemat Zod i plik testowy z 4 przypadkami testowymi.

Przepis 2: Zestandaryzowany composable do pobierania danych

Scenariusz: Twoje strony wywołują useFetch bezpośrednio z powieloną obsługą błędów. Potrzebujesz composable, który to ustandaryzuje.

Utwórz composables/useApiData.ts, który opakowuje useFetch Nuxta z konsekwentnymi wzorcami. Composable powinien: (1) Przyjmować URL string i obiekt opcji. (2) Automatycznie dodawać token auth z useState('auth-token') do nagłówka Authorization. (3) Transformować odpowiedzi błędów w typowany obiekt ApiError z statusCode, message i opcjonalnymi błędami na poziomie pól. (4) Zapewniać refresh(), który ponownie pobiera, clear(), który resetuje dane, i retry(), który ponawia po błędzie. (5) Poprawnie obsługiwać SSR: podczas renderowania po stronie serwera używać ciasteczek z request event zamiast useState do auth. (6) Typować zwracane wartości jako { data: Ref<T | null>, error: Ref<ApiError | null>, pending: Ref<boolean>, refresh, clear, retry }. Utwórz typowane wrappery: useApiGet<T>(url), useApiPost<T>(url, body), useApiPut<T>(url, body), useApiDelete(url). Przetestuj, że composable obsługuje deduplikację payloadu SSR i reaktywność po stronie klienta.

Oczekiwane wyjście: Plik composable z typowanymi wrapperami, typ ApiError i testy.

Przepis 3: Middleware auth z odświeżaniem JWT

Scenariusz: Chronione strony muszą sprawdzać uwierzytelnianie i przezroczyście odświeżać wygasłe tokeny bez przekierowania użytkownika.

To rusztowanie obejmuje dwa pliki middleware, plugin i composable — a podział SSR vs klient (ciasteczko na serwerze, useState na kliencie) to miejsce, gdzie narzędzia AI po cichu produkują niezgodność hydratacji. Wybierz workflow, który pozwala ci ją wyłapać.

Użyj trybu agenta, aby wygenerować middleware/auth.ts, middleware/guest.ts, plugin i useAuth() razem, a następnie zrób checkpoint przed zaakceptowaniem. Odświeżanie auth to klasyczne miejsce, gdzie AI czyta document.cookie podczas SSR — inline diff pozwala wyłapać API tylko-przeglądarkowe w setup, zanim wysadzi render serwera.

Wygeneruj całą powierzchnię auth w trybie headless, a następnie pilnuj granicy SSR hookiem: dodaj hook PostToolUse na middleware/*.ts i plugins/*.ts, który greppuje za document. lub window. poza strażnikiem onMounted/import.meta.client i zawodzi edycję. Uruchom claude -p "build the auth middleware, guest middleware, plugin, and useAuth composable", aby ścieżka przezroczystego odświeżania wylądowała w jednej turze.

Utwórz trzy elementy: (1) middleware/auth.ts — nazwany middleware trasy, który sprawdza prawidłowy token auth w useState('auth'). Jeśli brakuje, przekieruj do /login z parametrem query redirect zachowującym oryginalny URL. Jeśli token wygasł (sprawdź claim exp), wywołaj endpoint odświeżania przed zezwoleniem na nawigację. Jeśli odświeżanie się nie powiedzie, wyczyść stan auth i przekieruj do logowania. (2) middleware/guest.ts — dla stron logowania/rejestracji, przekieruj do /dashboard jeśli już uwierzytelniony. (3) plugins/auth.ts — plugin Nuxt uruchamiany przy inicjalizacji aplikacji, sprawdza istniejący refresh token w ciasteczkach i cicho przywraca sesję. Po stronie serwera czyta ciasteczko z eventu; po stronie klienta czyta z document.cookie. (4) Composable useAuth() udostępniający login(email, password), register(data), logout(), refreshToken() i obliczeniowy ref user. Chroń strony dodając definePageMeta({ middleware: 'auth' }). Przetestuj cały przepływ: logowanie ustawia tokeny, middleware blokuje nieuwierzytelniony dostęp, odświeżanie tokenu odbywa się przezroczyście, wylogowanie czyści wszystko.

Oczekiwane wyjście: Dwa pliki middleware, jeden plugin, jeden composable i testy integracyjne.

Przepis 4: Niestandardowy moduł Nuxt do SEO

Scenariusz: Każda strona potrzebuje spójnych meta tagów, danych strukturalnych i automatycznie generowanej mapy strony.

Utwórz lokalny moduł Nuxt w modules/seo/index.ts używając defineNuxtModule. Moduł powinien: (1) Automatycznie wstrzykiwać domyślne useHead dla każdej strony: charset, viewport, domyślny szablon tytułu i typowe meta tagi (og:site_name, twitter:card). (2) Zapewniać composable useSeo(options), który ustawia title, description, og:image, canonical URL i dane strukturalne JSON-LD dla bieżącej strony. (3) Rejestrować plugin Nitro generujący /sitemap.xml przez skanowanie wszystkich stron w katalogu pages i odpytywanie bazy danych o dynamiczne trasy. (4) Dodać trasę serwera robots.txt, która odwołuje się do URL mapy strony. (5) Konfiguracja przez nuxt.config z seo: { siteUrl, defaultImage, twitterHandle }. Przetestuj, że meta tagi renderują się poprawnie w wyjściu SSR.

Oczekiwane wyjście: Katalog modułu z index.ts, composable, pluginy Nitro dla sitemap i robots, oraz testy.

Przepis 5: Konfiguracja renderowania hybrydowego

Scenariusz: Twoje strony marketingowe powinny być statyczne, dashboard SSR, a blog ISR z 1-godzinną rewalidacją.

Oczekiwane wyjście: Zaktualizowany nuxt.config.ts, composable trybu renderowania i strona debugowania.

Przepis 6: Aktualizacje w czasie rzeczywistym z Server-Sent Events

Scenariusz: Twój dashboard potrzebuje aktualizacji na żywo dla zmian statusu zamówień bez złożoności WebSocket.

Zaimplementuj SSE w Nuxt. (1) Utwórz server/api/events.get.ts, który zwraca strumień SSE używając setResponseHeader(event, 'content-type', 'text/event-stream') i setResponseHeader(event, 'cache-control', 'no-cache'). Użyj createEventStream(event) z h3. Subskrybuj kanał Redis pub/sub dla aktualizacji zamówień i przesyłaj każdą aktualizację jako zdarzenie SSE z danymi JSON. Obsłuż rozłączenie klienta czyszcząc subskrypcję Redis. (2) Utwórz composables/useSSE.ts opakowujący EventSource z automatycznym ponownym łączeniem, typowanym parsowaniem wiadomości i czyszczeniem przy odmontowaniu komponentu. (3) Utwórz composables/useOrderUpdates.ts, który używa useSSE, filtruje zamówienia bieżącego użytkownika i reaktywnie aktualizuje store Pinia. (4) Pokaż powiadomienie toast gdy status zamówienia się zmieni. Przetestuj, że endpoint SSE odpowiada z poprawnymi nagłówkami i strumieniuje zdarzenia.

Oczekiwane wyjście: Trasa serwera SSE, dwa composables, integracja z Pinia i testy.

Przepis 7: Współdzielona warstwa Nuxt do ponownego użycia w wielu aplikacjach

Scenariusz: Trzy aplikacje Nuxt współdzielą komponenty, composables i style. Potrzebujesz współdzielonej warstwy.

Utwórz warstwę Nuxt w layers/ui-kit/. (1) Skonfiguruj layers/ui-kit/nuxt.config.ts z defineNuxtConfig i eksportuj komponenty, composables i preset Tailwind. (2) Dodaj współdzielone komponenty w layers/ui-kit/components/: Button, Input, Select, Modal, Card, Badge, Avatar — każdy z propsami TypeScript, stylowaniem Tailwind i wariantami (size: sm/md/lg, variant: primary/secondary/outline/ghost). (3) Dodaj współdzielone composables: useToast(), useConfirmDialog(), useBreakpoint(). (4) Dodaj preset Tailwind w layers/ui-kit/tailwind.preset.ts z kolorami systemu projektowego, czcionkami i odstępami. (5) W aplikacji konsumenta rozszerz przez extends: ['./layers/ui-kit']. Zweryfikuj, że auto-importy działają dla komponentów i composables warstwy. Napisz test potwierdzający, że komponenty warstwy renderują się na stronie konsumenta.

Oczekiwane wyjście: Katalog warstwy z konfiguracją, 7 komponentami, 3 composables, presetem Tailwind i testem integracyjnym.

Przepis 8: Warstwa bazodanowa z Drizzle ORM

Scenariusz: Twoja aplikacja Nuxt potrzebuje typowo-bezpiecznych zapytań do bazy danych, migracji i seedowania.

Warstwa bazodanowa to schemat plus typowane zapytania plus skrypt seed plus konfiguracja migracji — mnóstwo plików, które muszą zgadzać się co do tych samych typów. Relacje i krok migracji to miejsca, gdzie wybór narzędzia ma znaczenie.

Użyj trybu agenta, aby wygenerować schema.ts, funkcje zapytań i seed.ts w jednym przebiegu, obserwując inline diffy, by odwołania kluczy obcych (authorId references users) faktycznie się zgadzały. Uruchom drizzle-kit generate ze zintegrowanego terminala i przejrzyj wygenerowaną migrację SQL przed zastosowaniem.

Wygeneruj schemat i zapytania w trybie headless, a następnie uczyń kontrakt egzekwowalnym: dodaj hook PostToolUse na server/db/schema.ts, który uruchamia drizzle-kit generate, aby migracja nigdy nie rozjeżdżała się ze schematem. Podaj z powrotem wyjście przebiegu seed, jeśli dane z Faker naruszą ograniczenie — pętla terminalowa sprawia, że to jedno polecenie.

Zbuduj warstwę DB w worktree, aby trwająca migracja nigdy nie dotknęła twojej współdzielonej bazy dev, następnie wypchnij i pozwól recenzentowi w Cloud sprawdzić, czy każde zapytanie jest sparametryzowane, a join getPostsWithAuthor poprawnie paginuje przed scaleniem.

Skonfiguruj Drizzle ORM z PostgreSQL w Nuxt. (1) Utwórz server/db/schema.ts z tabelami: users (id uuid, email unique, name, hashedPassword, role enum, createdAt), posts (id uuid, title, slug unique, content text, authorId references users, status enum draft/published/archived, publishedAt, createdAt), comments (id uuid, postId references posts, authorId references users, content text, createdAt). (2) Utwórz server/db/index.ts inicjalizujący klienta drizzle ze zmiennej środowiskowej. (3) Utwórz server/db/queries/ z typowanymi funkcjami: getUserByEmail(email), getPostsWithAuthor(page, pageSize), createPost(data), getPostBySlug(slug) z autorem i liczbą komentarzy. (4) Utwórz drizzle.config.ts dla migracji. (5) Utwórz skrypt seed w server/db/seed.ts z 10 użytkownikami, 50 postami i 200 komentarzami używając Faker. (6) Dodaj server/utils/db.ts zapewniający cache’owaną instancję bazy danych. Przetestuj zapytania na testowej bazie danych.

Oczekiwane wyjście: Plik schematu, funkcje zapytań, konfiguracja, skrypt seed i testy zapytań.

Przepis 9: Blog z Nuxt Content

Scenariusz: Chcesz blog oparty na plikach Markdown z frontmatter, podświetlaniem kodu i spisem treści.

Skonfiguruj Nuxt Content v2 dla bloga. (1) Zainstaluj @nuxt/content i skonfiguruj z podświetlaniem kodu Shiki, kotwicami nagłówków i generowaniem TOC. (2) Utwórz content/blog/ z 3 przykładowymi postami używając frontmatter: title, description, author, date, tags array, image, draft boolean. (3) Utwórz pages/blog/index.vue listujący opublikowane posty posortowane malejąco po dacie z paginacją (10 na stronę). Pokaż tytuł, zajawkę, autora, datę i tagi. (4) Utwórz pages/blog/[...slug].vue dla poszczególnych postów z <ContentRenderer>, paskiem bocznym TOC, nawigacją prev/next i czasem czytania. (5) Utwórz components/content/ProseCode.vue do personalizacji bloków kodu z kopiowaniem do schowka. (6) Dodaj kanały RSS pod /api/rss.xml odpytując wszystkie opublikowane posty. Przetestuj listowanie bloga, renderowanie postów i wyjście RSS.

Oczekiwane wyjście: Konfiguracja Nuxt Content, przykładowe posty, strony bloga, niestandardowy komponent prose, trasa RSS i testy.

Przepis 10: Wdrożenie edge na Cloudflare Workers

Scenariusz: Wdróż swoją aplikację Nuxt na Cloudflare Workers z bazą danych D1, cache’owaniem KV i magazynem R2.

Skonfiguruj Nuxt do wdrożenia na Cloudflare Workers. (1) Ustaw nitro: { preset: 'cloudflare_module', cloudflare: { deployConfig: true } } w nuxt.config — preset Workers (module), który obsługuje D1, KV, R2 i waitUntil, oraz automatycznie generuje konfigurację wrangler. NIE używaj tutaj cloudflare-pages: to osobny cel Pages z innym wyjściem buildu i kształtem bindingów. (2) Utwórz wrangler.toml z bindingiem bazy danych D1, namespace KV dla sesji i bukietem R2 dla uploadów. (3) Utwórz server/utils/cf.ts zapewniający typowany dostęp do bindingów Cloudflare przez event.context.cloudflare.env. (4) Utwórz middleware sesji w server/middleware/session.ts czytający/zapisujący dane sesji do KV z 24-godzinnym TTL. (5) Utwórz trasę uploadu plików w server/api/upload.post.ts przechowującą pliki w R2 i zwracającą publiczny URL. (6) Zaktualizuj zapytania bazodanowe aby używać D1 zamiast PostgreSQL. (7) Dodaj wrangler.toml do lokalnego rozwoju z --local D1. Testuj lokalnie z npx wrangler dev.

Oczekiwane wyjście: Konfiguracja Nitro, wrangler.toml, narzędzia bindingowe, middleware sesji, trasa uploadu i zapytania D1.

Przepis 11: Strategia testowania aplikacji Nuxt

Scenariusz: Twoja aplikacja Nuxt ma zero testów. Potrzebujesz pokrycia dla komponentów, tras serwera i composables.

Postawienie środowiska testowego to konfiguracja plus narzędzia plus pierwsza partia testów — a wartość pojawia się dopiero wtedy, gdy te testy faktycznie uruchamiają się przy każdej zmianie, i tu workflow narzędzi się rozchodzą.

Użyj trybu agenta, aby napisać vitest.config.ts, helpery tests/utils/ i pierwsze testy komponentów, następnie uruchom je w zintegrowanym terminalu i podawaj inline z powrotem ewentualne awarie mountSuspended. Wizualny diff pomaga potwierdzić, że narzędzia testowe pasują do tego, jak montują się twoje prawdziwe strony.

Naturalne dopasowanie: wygeneruj środowisko w trybie headless, a następnie uczyń testy nieopcjonalnymi hookiem PostToolUse, który uruchamia npm run test:unit po edycjach *.vue lub server/**. Użyj claude -p "write @nuxt/test-utils tests for these three composables and two server routes" i pozwól mu iterować względem nieudanego wyjścia aż do zielonego.

Oczekiwane wyjście: Konfiguracja Vitest, narzędzia testowe, testy komponentów, testy tras serwera, testy composables i zaktualizowane skrypty.

Przepis 12: Audyt optymalizacji wydajności

Scenariusz: Twoja aplikacja Nuxt osiąga 60 punktów w Lighthouse. Przejścia między stronami są powolne, a bundle przekracza 1 MB.

Przeprowadź audyt i zoptymalizuj tę aplikację Nuxt pod kątem wydajności. (1) Uruchom npx nuxi analyze i zidentyfikuj chunki powyżej 50KB. Sprawdź, czy można je leniwie ładować lub zastąpić lżejszymi alternatywami. (2) Zamień wszystkie tagi <img> na <NuxtImg> z @nuxt/image dla responsywnych obrazów, leniwego ładowania poniżej fold i negocjacji formatu WebP/AVIF. (3) Włącz experimental.payloadExtraction dla osobnych plików payload. (4) Dodaj vite.build.rollupOptions.output.manualChunks do podzielenia kodu vendor na logiczne chunki. (5) Zaimplementuj <NuxtLoadingIndicator> z niestandardowym kolorem. (6) Dodaj useHead z podpowiedziami preload dla krytycznego CSS i czcionek. (7) Włącz cache’owanie routeRules dla stron statycznych. Zaraportuj wyniki Lighthouse przed i po. Cel: wydajność 90+, bundle poniżej 300KB początkowe.

Oczekiwane wyjście: Zaktualizowany nuxt.config, zamienione NuxtImg, konfiguracja podziału chunków i porównanie wydajności.

Gdy przepisy nie działają

Co dalej

Wzorce Vue.js dla przepisów na poziomie komponentów
Wzorce API do projektowania API konsumowanych przez twoje trasy serwera Nuxt
Przepisy bazodanowe do optymalizacji zapytań za twoimi trasami serwera