Pierwsze kroki

Wymagania

Podstawowym wymaganiem jest Node.js. Plik .nvmrc wskazuje wersję v24.12.0, natomiast package.json dopuszcza szerszy zakres:

// package.json
"engines": {
  "node": "^28 || ^26 || ^24 || ^22 || ^20",
  "npm": ">= 6.13.4"
}

Korzystając z nvm, wywołaj w katalogu projektu:

nvm use

Używaj wyłącznie wersji LTS, czyli parzystych

Wydania nieparzyste nie są testowane przez Quasara i mogą powodować błędy podczas budowania.

Instalacja

Sklonuj repozytorium odpowiadające rodzajowi projektu:

• Core

git clone git@bitbucket.org:moonbite/mooncore-frontend.git

• CRM

git clone git@bitbucket.org:moonbite/mooncrm-frontend.git

• CMS

git clone git@bitbucket.org:moonbite/mooncms-frontend.git

Następnie zainstaluj zależności:

npm ci

Polecenie uruchamia przy okazji skrypt prepare, który wywołuje husky install — hooki gita konfigurują się więc automatycznie.

Dokumentacja opisuje część wspólną trzech projektów

Wszystkie trzy opierają się na tej samej architekturze: module core, generatorze Plop, composables useCoreTable i useFormSubmit oraz konwencji <moduł>.<modele>.<akcja>. Różni je głównie zestaw modułów domenowych. Przykłady pochodzą z CMS-a.

Zmienne środowiskowe

Wzorzec zmiennych znajduje się w pliku .env.example:

# .env.example
APP_NAME=
API_BASE_URL=http://localhost:8000/api

Zmienna	Zastosowanie
API_BASE_URL	baseURL instancji axiosa (src/modules/core/services/http.js)
APP_NAME	Nazwa aplikacji prezentowana w interfejsie

Jak ładowane są pliki .env

Za wczytanie odpowiada build/env-parser.js, podpięty w quasar.config.js jako build.env: envLoader(). Pliki są ładowane w podanej kolejności, a każdy kolejny nadpisuje wartości z poprzedniego:

1. .env
2. .env.<ENV>
3. .env.<ENV>.local

Wartość <ENV> pochodzi ze zmiennej ENV, którą ustawiają skrypty npm:

// package.json
"dev":   "cross-env ENV=${ENV:=development} quasar dev",
"build": "cross-env ENV=${ENV:=production} quasar build"

Domyślnie npm run dev czyta warianty development, a npm run build — production.

Przykładowa zawartość pliku .env.development:

# .env.development
APP_NAME=YourProjectName
API_BASE_URL=http://api.yourdevsite.lh/api

Budując na inne środowisko, podaj zmienną ENV jawnie:

ENV=staging npm run build

Pliki *.local

Służą do nadpisań specyficznych dla danej maszyny. Znajdują się w .gitignore, więc nie trafiają do repozytorium.

Uruchomienie

npm run dev

Aplikacja uruchamia się w trybie SPA z hot reloadem. Przy pierwszym starcie Vite generuje pliki auto-imports.d.ts oraz components.d.ts. Oba są w repozytorium — zacommituj je po dodaniu nowego modułu.

Skrypty npm

Skrypt	Działanie
npm run dev	Serwer deweloperski (quasar dev), ENV=development
npm run build	Build produkcyjny do dist/, ENV=production
npm run lint	ESLint na src/**/*.{js,cjs,mjs,vue}
npm run format	Prettier na **/*.{js,vue,scss,html,md,json}
npm run make	Generator kodu — opisany w Modułach i generatorach

Lint podczas developmentu

vite-plugin-checker uruchamia ESLint w tle razem z npm run dev i prezentuje błędy bezpośrednio w przeglądarce, co zwalnia z ręcznego wywoływania npm run lint po każdej zmianie.

Hooki gita

Przed każdym commitem husky uruchamia lint-staged z następującą konfiguracją:

// package.json
"lint-staged": {
  "*.{js,vue}": "eslint --cache --fix",
  "*.{js,vue,css,md}": "prettier --write"
}

Formatowanie i proste błędy poprawiane są dzięki temu automatycznie.

Instalacja gotowego modułu

Część modułów utrzymywana jest w osobnych repozytoriach na Bitbuckecie. Instaluje je skrypt install-module.sh:

sh install-module.sh <nazwa-pakietu> [wersja]     # domyślna wersja: main

Sam skrypt nie wystarcza do uruchomienia modułu

Skrypt wypakowuje wyłącznie pliki. Przed rozpakowaniem wykonuje rm -rf src/modules/<moduł>, kasując niezacommitowane zmiany, a po wypakowaniu nie rejestruje modułu w aplikacji — wpisów w src/router/routes.js, src/i18n/{en,pl}/index.js, src/menu-items.js i quasar.config.js trzeba dopilnować ręcznie. Wymaga też dostępu SSH do Bitbucketa oraz GNU sed (na macOS — gsed). Pełny opis wraz z listą czynności ręcznych zawierają Moduły i generatory.