Frontend Scripts

This guide explains the main Zova script workflows in the Cabloy monorepo.

Shared rule

Zova can build SSR, SPA, Web, and Admin modes in one codebase. In Cabloy, contributors should usually start from the root scripts first, then drop into zova/package.json only when they need edition-specific detail.

Detect the edition first

Before choosing script examples, detect whether you are working in Cabloy Basic or Cabloy Start.

A practical rule is:

1. detect the edition first
2. then choose the correct script, flavor, and appMode path
3. only then document or automate edition-specific frontend examples

For the edition-detection workflow, see Cabloy Editions: For AI Development.

Cabloy Basic root wrappers

Cabloy Basic exposes these default Web and Admin wrappers:

npm run dev:zova:admin
npm run dev:zova:web
npm run build:zova
npm run build:zova:admin
npm run build:zova:web

They map to the cabloyBasicAdmin and cabloyBasicWeb flavors. Basic also includes the Commerce aggregate-and-surface wrappers:

# Customer Web or Operator Admin development server
npm run dev:zova:commerce:web
npm run dev:zova:commerce:admin

# Both Commerce SSR/REST artifact pairs, or one surface only
npm run build:zova:commerce
npm run build:zova:commerce:web
npm run build:zova:commerce:admin

npm run build:zova:all sequentially runs the focused Basic and Commerce batch builds. npm run init uses it to prepare every shipped Cabloy Basic SSR/REST flavor before Vona is initialized. For normal frontend work, continue to use build:zova or build:zova:commerce when only that suite's artifacts changed.

Zova standalone SSR development

The dev:zova:* commands start the Zova development server, which uses 9000 in the Cabloy Basic default environment. Use this Zova standalone SSR entry for page, route, and hydration iteration. It may be used as Vona's development proxy target, but direct access to 9000 does not prove the Vona request boundary or integrated acceptance.

Vona integrated SSR browser acceptance

The default Basic Web and Admin sites have browser smoke commands that exercise Vona integrated SSR through Vona SSR dispatch at the managed run's dynamically allocated test listener, not through the ordinary Vona development listener (7102 by default) or the Zova standalone SSR development-server port. Vona supplies the API origin at runtime, so no Zova .env change or rebuild is needed solely for the test port; see Runtime API origins in Vona integrated SSR.

Prepare current SSR and REST artifacts explicitly when frontend output has changed:

# Web only
npm run build:zova:web

# Admin only
npm run build:zova:admin

# Both default Basic sites, then a managed local run
npm run build:zova
npm run deps:vona
npm run test:e2e cabloy-basic home-user-account

The sole managed npm run test:e2e command starts a fresh local Vona worker with --workers=1 --flavor=normal --mode=test, then runs the selected specs against Vona integrated SSR. Test-mode startup initializes test resources without a separate db:reset; browser commands consume already-built artifacts and do not rebuild them. Confirm exclusive ownership of the effective test database, _local Redis namespace, public/runtime paths, APP_NAME, API origin, and listener before startup; a free port alone is insufficient.

Place flat spec basenames directly after the npm script name. Use npm's -- delimiter before Playwright options. With no names, every spec in repo-e2e/specs runs. Native --grep and --grep-invert remain available, and repeatable --tag values require all listed tags:

npm run test:e2e cabloy-basic home-user-account -- --grep @flow
npm run test:e2e a-commerce -- --tag @web --tag @smoke

For the complete Basic tag vocabulary and managed-runner argument boundaries, see Repo Scripts. E2E_BASE_URL must be unset: externally managed targets are unsupported.

Cabloy Start root wrappers

Cabloy Start is the public MIT-licensed edition. Its default root wrappers use the cabloyStartAdmin and cabloyStartWeb flavors:

npm run dev:zova:admin
npm run dev:zova:web
npm run build:zova
npm run build:zova:admin
npm run build:zova:web

Cabloy Start does not expose the Basic Commerce wrapper family.

Start SSR browser acceptance

The Start Web and Admin browser baseline exercises Vona integrated SSR dispatch at the effective local test-mode server port. Prepare current SSR and REST artifacts, then use the managed local command:

npm run build:zova
npm run deps:vona
npm run test:e2e

Start uses one E2E command and one fresh managed local test-mode lifecycle:

npm run test:e2e       fresh managed local test-mode suite run

Select flat spec basenames and filter scenarios or surfaces with runner tags and native Playwright arguments. Current Start scenarios use tags including @web, @admin, @smoke, @layout, @cabloy-admin, @account, @ssr, and @flow:

npm run test:e2e cabloy-start
npm run test:e2e cabloy-start -- --tag @web
npm run test:e2e cabloy-admin -- --tag @admin --tag @cabloy-admin
npm run test:e2e cabloy-start -- --grep ATP-START-FLOW-01

Start does not support externally managed E2E targets: E2E_BASE_URL must be unset. The command requires the configured local port to be available and starts one Vona worker with --flavor=normal --mode=test; Playwright does not reuse an existing process. Test-mode startup initializes test state. Confirm exclusive ownership of the test database, Redis namespace, and public/runtime paths before running it. The command does not replace the paired build/dependency-sync prerequisite; do not change shared environment identity or ports to avoid a busy resource.

Zova script model

The underlying Zova package organizes scripts around app mode and flavor.

Examples from the current source include:

• dev:ssr:admin
• build:ssr:admin
• preview:ssr:admin
• dev:ssr:web
• build:ssr:web
• preview:ssr:web
• dev:ssr:cabloyBasicAdmin
• build:ssr:cabloyBasicAdmin
• build:rest:cabloyBasicAdmin
• dev:ssr:cabloyStartAdmin
• build:ssr:cabloyStartAdmin
• build:rest:cabloyStartAdmin

Cabloy Basic

The public repository supports Basic-specific flavors:

• cabloyBasicAdmin
• cabloyBasicWeb

Representative Zova commands are:

cd zova && npm run dev:ssr:cabloyBasicAdmin
cd zova && npm run build:ssr:cabloyBasicAdmin
cd zova && npm run build:rest:cabloyBasicAdmin

Cabloy Start

The separate public Cabloy Start repository supports Start-specific flavors:

• cabloyStartAdmin
• cabloyStartWeb

Representative Zova commands are:

cd zova && npm run dev:ssr:cabloyStartAdmin
cd zova && npm run build:ssr:cabloyStartAdmin
cd zova && npm run build:rest:cabloyStartAdmin

Workflow guidance

When documenting or automating frontend scripts:

• start from the root wrappers for the detected edition
• detect the edition before choosing flavor-specific examples
• verify the exact flavor before writing edition-specific examples
• use REST/type generation commands deliberately when backend integration depends on them
• understand the mode/appMode/flavor model before changing script families; see Environment and Config Guide
• enable or package frontend mock support deliberately when development depends on fake-server behavior; see Mock Guide
• use Frontend Quickstart when the reader first needs the end-to-end onboarding story rather than only a script reference