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

```bash
corepack enable
pnpm install
pnpm dev
```

Poznamka:

- projekt ocakava Node `^22.12.0 || >=24`

Ak chces rovno pripravit release image namiesto lokalneho dev servera:

```bash
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:

```env
NUXT_PUBLIC_API_BASE_URL=/api
NUXT_PUBLIC_API_TIMEOUT_MS=10000
NUXT_PUBLIC_AUTH_MODE=disabled
```

Ak chces lokalny mock auth:

```env
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:

```ts
definePageMeta({
  requiresAuth: true
})
```

Priklad s rolou:

```ts
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:

```ts
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:

```bash
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:

```vue
<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:

```ts
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:

```bash
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build
```

Ak menis formatovanie:

```bash
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:

```bash
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`