Frontend Development Environment

The ApexOS frontend is a Lit-based TypeScript application. This page covers getting a local checkout building, the build targets you will actually use, and how to point your development frontend at a real ApexOS instance.

Prerequisites

• Node.js 24.18.0 — the exact version is pinned in the repository's .nvmrc. If you use nvm, run nvm use in the repo root and you will get the right version automatically.
• Yarn — the repository is a Yarn workspace project (dependencies are locked in yarn.lock). All package scripts assume Yarn, not npm.

Initial setup

script/setup

This resolves all frontend dependencies the application needs for development (it delegates to script/bootstrap).

Build targets

The build pipeline is driven by gulp. Two entry tasks matter for day-to-day work:

Task	Wrapper script	What it does
develop-app	script/develop	Development build with NODE_ENV=development: cleans the output, generates icons, pages, translations and locale data, copies static assets, then starts the bundler in watch mode.
build-app	script/build_frontend (also yarn build)	Production build with NODE_ENV=production: same generation steps plus license generation, a production bundle, generated pages/service worker, and output compression.

You normally never invoke gulp directly — use the wrapper scripts:

# development build with file watching
script/develop

# production build
script/build_frontend

Pointing the dev frontend at a device

The development build bakes in the URL of the core instance it should talk to via the APEX_URL environment variable. The generated entry HTML reads process.env.APEX_URL and uses it as the backend URL for the frontend's connection bootstrap.

The convenience script script/develop_and_serve wires this up for you: it runs a watching development build and serves the result on a local port, so you can develop against any reachable ApexOS instance without linking your checkout into a running core.

# defaults: frontend on http://localhost:8124, backend at http://localhost:1702
script/develop_and_serve

# point at a remote / production device
script/develop_and_serve -c https://myhost.duckdns.org:1702

# serve the frontend on a different port
script/develop_and_serve -p 8654

Options:

• -c <url> — the core instance the frontend connects to. This can be any existing production instance; it does not need to be a locally hosted development build.
• -p <port> — the port the frontend itself is served on (default 8124; inside a devcontainer the frontend is served on port 1702 internally and forwarded to 8124 on the host).

Under the hood the script simply runs APEX_URL="$coreUrl" ./script/develop and serves the apex_frontend output directory with a single-page-app fallback.

:::caution Login sessions stick to their backend If you already have an active login session in a frontend served from a given URL, that session keeps using the core it was created against until you log out. If you reuse the same frontend URL with a different -c backend, log out first so the new backend actually takes effect. :::

Linting and tests

yarn lint        # eslint + prettier + tsc + lit-analyzer
yarn format      # auto-fix eslint + prettier
yarn test        # vitest unit tests
yarn test:e2e    # Playwright end-to-end suites (demo, app, gallery)