Build & Deploy

npm Scripts

Command	Script	Purpose
npm run dev	vite	Start the Vite dev server with HMR
npm run typecheck	vue-tsc --noEmit	Run TypeScript + Vue SFC type checks only
npm run build	vite build	Build the app bundle to dist/
npm run preview	npm run build && vite preview	Build and preview the production bundle locally
npm run docs:dev	vitepress dev docs	Start VitePress dev server for documentation
npm run docs:build	vitepress build docs	Build the documentation site to dist/docs/
npm run docs:preview	vitepress preview docs	Preview the built documentation site
npm run build:all	npm run build && npm run docs:build	Build both app and docs into dist/
npm run test:unit	vitest run tests/unit	Run unit tests in CI mode
npm run test:unit:watch	vitest tests/unit	Run unit tests in watch mode
npm run test:integration	vitest run tests/integration	Run composable/persistence integration tests
npm run test:integration:watch	vitest tests/integration	Run integration tests in watch mode
npm run test:ci	npm run test:unit && npm run test:integration	Run non-browser test gates (unit + integration)
npm run test:e2e	playwright test	Run critical browser E2E journeys
npm run test:e2e:headed	playwright test --headed	Run E2E journeys with visible browser
npm run check:i18n	node scripts/check-i18n.mjs	Validate i18n key parity across locale catalogs
npm run check:docs-sync	node scripts/check-docs-sync.mjs	Validate docs claims against current source truth
npm run check	npm run check:i18n && npm run check:docs-sync && npm run typecheck	Fast validation pipeline (i18n + docs sync + type-check)
npm run verify	npm run check && npm run test:ci && npm run build && npm run docs:build	Local CI-equivalent gate (no browser E2E)
npm run test	npm run test:unit	Default test entrypoint
npm run generate:meta-assets	node scripts/generate-meta-assets.cjs	Generate favicons, icons, and OG image from logo

Build Output

The production build writes to dist/:

dist/
├── index.html          # App entry
├── assets/             # App JS/CSS bundles
└── docs/               # VitePress documentation site
    ├── index.html
    └── ...

The app uses a relative base path (base: "./" in Vite config), so it can be served from any directory. The docs site uses an absolute base path (/parallax-designer/docs/) to match the GitHub Pages deployment URL.

Vite Configuration

The Vite config is minimal:

export default defineConfig({
  base: "./",
  plugins: [vue(), tailwindcss()],
});

• base: "./" — Relative asset paths, enabling deployment to any URL path
• vue() — Vue SFC compilation via @vitejs/plugin-vue
• tailwindcss() — Tailwind CSS v4 integration via @tailwindcss/vite

GitHub Pages Deployment

The project deploys to GitHub Pages automatically via GitHub Actions on every push to master or main.

Workflow overview (.github/workflows/build.yml + .github/workflows/tag-working-snapshot.yml):

Build order constraint

The app build must run first — Vite empties dist/ before writing. The docs build then writes into the existing dist/docs/ without wiping app files.

1. Checkout the repository
2. Setup Node.js 22 with npm cache
3. Install dependencies (npm ci)
4. Validate i18n + docs sync + type-check (npm run check)
5. Build the app (npm run build) — writes to dist/
6. Build the docs (npm run docs:build) — writes VitePress output to dist/docs/
7. Upload the entire dist/ directory as a Pages artifact
8. Deploy to the github-pages environment
9. Tag snapshot after successful deploy (work-YYYYMMDD-HHMMSS-<sha7>)

Current test execution scope

The deploy workflow currently runs validation/build steps (npm run check, npm run build, npm run docs:build) but does not yet run test:unit, test:integration, or test:e2e.

The result is:

URL	Content
https://robert-hoffmann.github.io/parallax-designer/	The Parallax Designer app
https://robert-hoffmann.github.io/parallax-designer/docs/	This documentation site

Build order matters: the app build creates dist/ (Vite empties it first), then the docs build writes into the existing dist/docs/ subdirectory without wiping the app files.

Working Snapshot Tags

After a successful deploy workflow run from a push to main or master, CI creates one annotated Git tag:

• Format: work-YYYYMMDD-HHMMSS-<sha7>
• Points to the exact deployed commit
• Includes a commit summary since the previous work-* tag
• Skips duplicate tagging when the same commit already has a work-* tag

This gives you rollback points for known-good pushes without release PR workflows.