Initial commit
This commit is contained in:
AI
+293
@@ -0,0 +1,293 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user