Files
liqa/docs/development.md
T
Andrii Arsenin 522c49d7c2 docs: bring docs up to date and drop unused keys setting
- rewrite architecture, development, mcp and scenario docs to match the
  current code: single container, all mcp tools, runs, versioning,
  timeouts, settings, client routing and dev setup
- rewrite README as a general overview without liquio-specific wording
- remove the unused KEYS_DIR setting and ./keys compose mount
- remove the unused result parameter from step code execution
- complete .env.example with the file storage settings and fix the
  DB_PATH default
2026-09-30 21:18:41 +03:00

8.4 KiB

Development

Prerequisites

  • Node.js 24+ (required by engines in package.json; the Docker image uses Node.js 24)
  • Docker + Docker Compose

The repository is a npm workspace monorepo with two packages:

Workspace Directory Description
server server/ NestJS API + MCP server
client client/ React 19 + Vite admin UI

Install all dependencies from the repo root:

npm install
npx playwright install --only-shell chromium   # first time only: headless Chromium for the server

Copy .env.example to .env and fill in the required values before running.

Environment variables (server)

All settings are validated at startup by server/src/config/app.config.ts.

Variable Default Description
NODE_ENV development Shown in the startup log
PORT 3000 HTTP port
DB_PATH data/liqa.db SQLite database file
FILES_DIR data/files Where scenario files and run artifacts are stored
FILE_RUN_EXPIRATION_DAYS 7 How long run artifacts (downloads, failure dumps, traces) are kept
FILE_CLEANUP_CRON 0 3 * * * When expired files are deleted
SESSION_IDLE_TIMEOUT_MINUTES 30 Idle timeout before open sessions are closed
SESSION_DELETE_CLOSED_DAYS 7 Retention period for closed sessions
PLAYWRIGHT_TRACE_MODE off Default Playwright trace mode for runs: on, retain-on-failure or off (see scenario.md)
CLIENT_DIR (empty) Directory with the built client to serve at / (the Docker image sets it to client); empty means the server doesn't serve the UI
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH (Playwright default) Path to a Chromium binary to use instead of Playwright's own. Not set in Docker: the image ships Playwright's chromium-headless-shell (matching the Playwright version) under PLAYWRIGHT_BROWSERS_PATH=/ms-playwright.

Starting the application

Server

Development (watch mode, restarts on file changes):

npm -w server run start:dev

Production build, then start:

npm -w server run build
npm -w server run start:prod

The server listens on port 3000 by default.

Client

Development (Vite dev server with HMR):

npm -w client run dev

The Vite dev server runs on http://localhost:5173. It has no API proxy: the client calls VITE_API_URL (default /api/v1 on its own origin), and the server allows CORS from http://localhost:5173. So point it at a running server:

npm -w client run dev:compose-api                          # API of the compose container (localhost:13000)
VITE_API_URL=http://localhost:3000/api/v1 npm -w client run dev   # API of a locally started server

Production build:

npm -w client run build

The built files are emitted to client/dist/.


Running tests

Server (Jest)

npm -w server run test

Run a single spec file:

npm -w server run test -- --no-coverage test/scenario.controller.spec.ts

Watch mode:

npm -w server run test:watch

Print the NestJS logs of the test app (they're silenced by default; DEBUG=test):

npm -w server run test:debug

Client (Vitest + Storybook)

Storybook interaction tests (runs all *.stories.tsx files):

npm -w client run test:storybook

Launch Storybook dev server (with live preview):

npm -w client run storybook

Formatting code

Both workspaces use Prettier.

Server — rewrites src/**/*.ts and test/**/*.ts:

npm -w server run format

Client — rewrites src/**/*.{ts,tsx} and .storybook/**/*.{ts,tsx}:

npm -w client run format

Linting

Both workspaces use ESLint with typescript-eslint. The client also includes eslint-plugin-react-hooks and eslint-plugin-react-refresh.

Server:

npm -w server run lint        # report issues
npm -w server run lint:fix    # report and auto-fix

Client:

npm -w client run lint        # report issues
npm -w client run lint:fix    # report and auto-fix

Both workspaces target zero errors. Run lint before committing.


Building the container

The root Dockerfile builds a single image with the whole application: it builds the client and the server in separate stages, and the runtime image runs the server, which also serves the built client (CLIENT_DIR).

The runtime image uses Playwright's headless-only Chromium build (chromium-headless-shell) with just the shared libraries it links against, plus DejaVu and Liberation fonts (Liberation is metric-compatible with Arial/Times, so pages lay out as they would with those fonts). All browser launches are headless, so the full desktop Chromium isn't installed. If a new Playwright version needs another library, ldd on the chrome-headless-shell binary in the image lists what's missing.

docker compose build

To rebuild without the layer cache:

docker compose build --no-cache

Running with Docker Compose

Start (detached):

docker compose up -d

Build and start in one step:

docker compose up -d --build

Everything is served by the single liqa container at http://localhost:13000: the UI at /, the REST API at /api/v1, MCP at /mcp, Swagger at /docs and health at /health. Unknown paths outside those routes get the client's index.html, so client-side routes survive a page refresh.

When switching from the old two-container setup (server + client), remove the old containers with docker compose up -d --build --remove-orphans.

The SQLite database and stored files are persisted in ./data/, which is volume-mounted into the container.

Stop and remove containers:

docker compose down

View logs:

docker compose logs -f

Client overview

The client (client/) is a React 19 + TypeScript SPA built with Vite. It provides a browser UI for managing scenarios, runs, snippets, credentials, environments and sessions, and for importing exported YAML.

Tech stack

Library Purpose
React 19 + TypeScript UI framework
Vite 6 Dev server and bundler
react-router-dom 7 (BrowserRouter) Client-side routing
@tanstack/react-query Data fetching (cross-scenario runs list)
i18next + react-i18next Internationalisation
lucide-react Icon library
@monaco-editor/react Code editor for steps and snippets
react-markdown + highlight.js Markdown descriptions and code highlighting
yaml YAML export of entities
moment Relative timestamp formatting
ESLint 10 + Prettier Linting and formatting
Storybook 10 + Vitest Component development and testing

Directory layout

client/
  src/
    api/          API client (client.ts) and types (types.ts)
    components/   modals/ - run, export, export logs and delete confirmation modals
    hooks/        useTheme, usePageTitle, useRunDefaults, useImportFile
    i18n/         i18next bootstrap + locales/en.json
    lib/          highlight.js setup, API error toast events
    pages/        scenario/, run/, snippet/, credential/, environment/, session/, import/
    ui/           Reusable component library (Badge, Button, Card, CodeEditor, Modal,
                  Select, SidePanel, Table, Toast, ... - see ui/index.ts)
  .storybook/
    stories/      *.stories.tsx for ui/ components

Routing

BrowserRouter with plain paths. The root and unknown paths redirect to /scenarios. The server answers these paths with the client's index.html (see architecture.md), so they work on refresh.

Route Page
/scenarios Scenario list
/scenarios/:id Scenario details (steps, versions, credentials, used snippets, files)
/scenarios/:id/runs, /scenarios/:id/runs/:runId Runs of a scenario, run details
/runs Cross-scenario runs list
/snippets, /credentials, /environments, /sessions Entity lists (plus /:id, /new, /:id/edit where applicable)
/import Central import

Theming

Light/dark theme is toggled by the ThemeSwitcher button in the sidebar footer. The selection is persisted to localStorage and applied as data-theme on <html> before React mounts (anti-FOUC inline script in index.html).

The sidebar footer also shows the app version read from the workspace root package.json and injected via Vite define.