nuxt4/quick_start.md

Quick Start

Tento dokument je rychly start po vytvoreni projektu z template.

Ak nechces citat celu dokumentaciu, chod podla tychto krokov.

1. Spusti Projekt

corepack enable
pnpm install
pnpm dev

Poznamka:

• projekt ocakava Node ^22.12.0 || >=24

Ak chces rovno pripravit release image namiesto lokalneho dev servera:

docker build -t nuxt-workspace-template:latest .
docker run --rm -p 3000:3000 nuxt-workspace-template:latest

Potom otvor http://localhost:3000.

Poznamka:

• runtime image je distroless Node 24 image urceny pre release a deploy

Co Spravit Hned Po Spusteni

Po tom, co aplikacia bezi, urob aspon tieto zakladne kroky:

1. vytvor .env z .env.example a nastav minimalne API a auth hodnoty
2. uprav branding v package.json, nuxt.config.ts a textoch v i18n/locales
3. rozhodni auth mod: disabled, mock alebo userinfo
4. rozhodni, ci pojdes cez vlastne wrappery v api/wrappers, alebo cez OpenAPI codegen
5. nahrad demo obsah v app/pages/index.vue prvou realnou obrazovkou alebo dashboardom
6. skontroluj globalne styly v app/assets/styles
7. pred vacsou zmenou pust pnpm lint, pnpm typecheck, pnpm test:run a pnpm build

Kde to najdes podrobne:

• .env a runtime config: nizsie v tomto dokumente a v programing_guide.md
• branding a preklady: sekcia Uprav Branding
• auth: sekcia Rozhodni Sa O Auth
• API a OpenAPI: sekcia Rozhodni Sa O API Integracii
• prva feature: sekcia Vytvor Prvu Feature

2. Vytvor .env

Skopiruj .env.example do .env a uprav hodnoty podla projektu.

Minimalny start:

NUXT_PUBLIC_API_BASE_URL=/api
NUXT_PUBLIC_API_TIMEOUT_MS=10000
NUXT_PUBLIC_AUTH_MODE=disabled

Ak chces lokalny mock auth:

NUXT_PUBLIC_AUTH_MODE=mock

3. Uprav Branding

Najcastejsie prve zmeny:

• nazov projektu v package.json
• title a meta v nuxt.config.ts
• texty v i18n/locales/sk.json
• texty v i18n/locales/en.json
• obsah domovskej stranky v app/pages/index.vue

Odporucanie:

• nenechaj template texty v produkcnom projekte

4. Rozhodni Sa O Auth

Template podporuje volitelny auth skeleton.

Moznosti:

• disabled pouzi, ak aplikacia auth nepotrebuje
• mock pouzi pri lokalnom vyvoji bez realneho prihlasenia
• userinfo pouzi, ak backend alebo proxy vracia user info endpoint

Priklad ochrany route:

definePageMeta({
  requiresAuth: true
})

Priklad s rolou:

definePageMeta({
  requiresAuth: true,
  roles: ['ADMIN']
})

5. Rozhodni Sa O API Integracii

Mas 2 hlavne cesty:

• bez OpenAPI pouzivaj useApi() a doplnaj vlastne wrappery do api/wrappers
• s OpenAPI nahraj specifikaciu do openapi-spec a vygeneruj klienta

Priklad pouzitia API:

const api = useApi()
const health = await api.example.getHealth()

Ak mas OpenAPI:

1. nahrad openapi-spec/example-api.yaml
2. uprav openapi-ts.config.ts
3. spusti:

pnpm generate:api

Poznamka:

• generator bezi cez @hey-api/openapi-ts, takze netreba Javu

6. Stavaj UI S Nuxt UI

Template pouziva Nuxt UI ako predvolenu komponentovu vrstvu.

Pouzivaj najma:

• UButton
• UCard
• UInput
• USelect
• UFormField
• UAlert

Priklad:

<template>
  <UCard>
    <template #header>
      <h2>Nova stranka</h2>
    </template>

    <UFormField label="Nazov">
      <UInput v-model="name" />
    </UFormField>

    <UButton>Ulozit</UButton>
  </UCard>
</template>

<script setup lang="ts">
const name = ref('')
</script>

Odporucanie:

• nebuduj novu vrstvu BaseButton, BaseInput, BaseCard, ak na to nie je silny dovod

7. Pouzivaj Pinia Len Na Zdielany Stav

Pripravene store-y:

• useAuthStore()
• useUiStore()

Pouzivaj ich na:

• user/session stav
• loading
• notifikacie

Nepouzivaj ich na:

• kazdy maly lokalny input
• docasny stav jedneho formulara, ak ho nepotrebuje viac casti appky

Priklad:

const uiStore = useUiStore()

uiStore.pushNotification({
  title: 'Ulozene',
  message: 'Operacia prebehla uspesne.',
  tone: 'success'
})

8. Vytvor Prvu Feature

Odporucany postup pri novej feature:

1. vytvor route v app/pages
2. vytvor alebo dopln API wrapper v api/wrappers
3. ak treba, vytvor store v app/stores
4. dopln preklady do i18n/locales
5. postav UI pomocou Nuxt UI

Priklad:

• app/pages/users/list.vue
• api/wrappers/users.ts
• app/stores/users.ts

9. Over Kvalitu

Pred vacsou zmenou alebo commitom pustaj:

pnpm lint
pnpm typecheck
pnpm test:run
pnpm build

Ak menis formatovanie:

pnpm format:fix

Template uz obsahuje automaticke testy pre:

• auth a ui store-y
• auth plugin a auth middleware
• API wrapper a API plugin
• logger plugin a useLogger()
• konzistenciu i18n klucov

Ak chces rychly smoke check len pre testovaciu kostru template-u, pouzi:

pnpm vitest run tests/auth.plugin.spec.ts tests/auth.middleware.spec.ts tests/i18n.locales.spec.ts tests/api.plugin.spec.ts tests/logger.plugin.spec.ts tests/use-logger.spec.ts

Poznamka:

• Vitest aliasy pre Nuxt importy su nastavene vo vitest.config.ts

10. Co Zmenit Ako Prve V Realnom Projekte

Najcastejsie prve upravy:

• branding a preklady
• title a meta udaje
• .env konfiguracia
• auth mod
• API base URL
• vlastna domovska stranka
• prvy realny API wrapper
• prva chranena route, ak treba auth

Odporucane Minimalne Rozhodnutia Na Start

Predtym, nez zacnes feature vyvoj, rozhodni aspon toto:

1. bude auth disabled, mock alebo userinfo?
2. bude FE/BE kontrakt rieseny cez OpenAPI?
3. budete generovat klientov do openapi-client?
4. budete drzat globalny stav v Pinia store-och?
5. zostavate pri Nuxt UI ako hlavnej UI vrstve?

Ked Chces Ist Dalej

Podrobnejsi popis najdes v:

• readme.md
• programing_guide.md
• openapi-spec/README.md