Appearance
Building from source
Replora's source is one pnpm monorepo: the Laravel and React application, the tracking script, the npm packages for websites and the shared UI kit. This page sets up a development copy, explains what pnpm build produces and lists the checks a change must pass (types, translations, module independence and 100 % test coverage).
Requirements
| Tool | Version |
|---|---|
| Node.js | 22 recommended (engines: ^20.19.0 or >=22.12.0) |
| pnpm | 10 (the repository pins [email protected] through packageManager; corepack enable picks it up) |
| PHP | 8.3 or newer, with pdo_pgsql, mbstring, openssl, zlib, zip, sodium, fileinfo (and pcov for coverage) |
| Composer | 2 |
| PostgreSQL | 13 or newer |
| Redis | Optional (cache, queue); the database works too |
| Docker | Optional, for the local services below |
Project layout
text
replora/
├── apps/standalone/ the application (Laravel 13 + React 19, Vite)
│ ├── app/ core: accounts, team, tokens, settings, updates, licensing, contracts, events
│ ├── modules/ feature modules (both editions)
│ ├── saas/ SaaS edition: saas/modules and their dashboard entry
│ ├── resources/js/ the dashboard shell
│ ├── resources/core-pack.json the modules the signed module pack carries
│ ├── config/ routes/ database/ lang/ tests/
│ └── tools/ check-modules.php, check-imports.php, check-docs.php, check-coverage.php
├── packages/
│ ├── tracker/ t.js, the tracking script (TypeScript + rrweb, built with esbuild)
│ ├── browser/ @replora/browser (npm)
│ ├── react/ @replora/react (npm)
│ └── ui/ @replora/ui, the dashboard's UI kit
├── tools/ release.mjs, release-core.mjs, key generators, i18n tools, offline-player.mjs
├── docs/openapi.yaml the REST API description
├── documentation/ these docs (VitePress)
└── docker-compose.yml PostgreSQL, Redis, MinIO for developmentSet up a development copy
Start the services (or use your own PostgreSQL):
shdocker compose up -dService Address Credentials PostgreSQL 17 127.0.0.1:5433, databasereplorareplora/secretRedis 7 127.0.0.1:6380— MinIO (S3) API 127.0.0.1:9002, console127.0.0.1:9003, bucketrecordingsreplora/replora-secretThe ports are shifted by one so they don't collide with services already running on your machine.
Install the JavaScript dependencies (the whole workspace):
shpnpm installInstall the PHP dependencies and configure the app:
shcd apps/standalone composer install cp .env.example .env php artisan key:generateThe repository's
.env.exampleis the developer template (local services above, debug on,REPLORA_MODE=single). SetREPLORA_MODE=saasto work on the SaaS edition. See Environment.Install: open the app and use the web installer, or run it on the command line:
shREPLORA_LICENSE_REQUIRED=false php artisan replora:install --url=http://127.0.0.1:8010 --skip-license--skip-licenseworks only whileREPLORA_LICENSE_REQUIREDisfalseand every module is present (true in a development copy); otherwise the installer asks for a purchase code. Alternatively setREPLORA_INSTALLED=truein.env, runphp artisan migrateand create an administrator withphp artisan replora:admin.Build and run:
shcd ../.. # repository root pnpm build # tracker, npm packages, dashboard cd apps/standalone php artisan serve --port=8010 php artisan queue:work # in a second terminal: recordings are processed by the queueFor the dashboard with hot reload run
pnpm dev(Vite) at the root instead of rebuilding.
Record yourself
Add a website in the dashboard with 127.0.0.1 as allowed domain, put its snippet on any local page (or open /demo after setting REPLORA_DEMO_SITE), and watch the session arrive. ?sr_diagnostics=1 shows what the tracker does.
What pnpm build does
| Step | Command | Output |
|---|---|---|
| 1. Offline player | node tools/offline-player.mjs | modules/Recordings/Resources/offline/player.{js,css}: the player embedded in downloaded recordings |
| 2. Tracker | pnpm --filter @replora/tracker run build (esbuild, ES2019, IIFE, minified) | modules/Recordings/Resources/tracker/t.js, served at /t.js |
| 3. npm packages | pnpm run build:packages (TypeScript) | packages/browser/dist, packages/react/dist |
| 4. Dashboard | pnpm --filter @replora/standalone run build (Vite) | apps/standalone/public/build |
The tracker and the offline player are committed into the Recordings module's folder like any other file, so a server never needs node_modules. With REPLORA_EDITION=single (or without the saas/ folder) the dashboard is built without the SaaS pages.
| Script (repository root) | What it does |
|---|---|
pnpm build | Everything above |
pnpm build:tracker | Only t.js |
pnpm --filter @replora/tracker run watch | Rebuilds t.js on every change (with an inline source map) |
pnpm build:packages | Only @replora/browser and @replora/react |
pnpm dev | Vite dev server for the dashboard |
pnpm test | All Vitest tests (UI kit, tracker, npm packages, dashboard logic) |
pnpm test:coverage | The same with coverage; fails below 100 % lines, functions, statements and branches |
pnpm typecheck | TypeScript of the tracker, both npm packages and the dashboard |
pnpm i18n | tools/check-i18n.mjs: every interface text translated in every language |
pnpm i18n:write | Adds missing keys (empty) to the language files and removes unused ones |
pnpm release … | Release builds; see Releases & module packs |
Tests and checks
Everything below must pass before a change goes in.
JavaScript
sh
pnpm typecheck
pnpm test:coverage
pnpm i18nCoverage counts the tracker, @replora/browser, @replora/react, the dashboard's logic (resources/js/lib/*.ts, modules/*/Resources/js/*.ts) and the SaaS public pages' scripts. React screens themselves are checked in a real browser instead.
tools/check-i18n.mjs collects every t('…') text (and the labels the shared controls translate themselves) per package and fails when a language file misses one or has it empty, and on texts that are still not translatable: string literals shown in JSX, template strings with words in JSX, toast() with a plain string (add // i18n-ignore on the line to allow one). It checks the server's __() texts against the JSON catalogs the same way (lang/<lang>.json, <module>/Resources/lang/<lang>.json). Languages: en es fr de pt it ru zh ja ko tr id ar.
Two helpers for translators: node tools/i18n-pending.mjs export <dir> writes every untranslated text per language, import <dir> puts the translations back; node tools/i18n-reuse.mjs <other repo> fills empty translations from another product's catalogs where the English text is identical.
PHP
sh
cd apps/standalone
composer check| Step | Fails when |
|---|---|
tools/check-imports.php | A PHP file uses a fully-qualified class name inline instead of a use import |
tools/check-docs.php | A class, interface, trait or enum in app/, modules/ or saas/, or one of its public methods, has no PHPDoc |
tools/check-modules.php | A module uses another module's classes, a module.json doesn't match its folder, or shared code names a SaaS module |
vendor/bin/pint --test | Code style differs from Pint's (vendor/bin/pint fixes it) |
| PHPUnit with PCOV | A test fails |
tools/check-coverage.php … 100 | Any line of app/, modules/ or saas/modules/ is not covered (lists each uncovered line) |
Run a part of the suite while working: php artisan test --compact --filter=EventsTest or vendor/bin/phpunit modules/Events. The suites are Unit, Feature and Modules (every *Test.php in modules/ and saas/modules/).
The test database
phpunit.xml sets DB_CONNECTION=pgsql and DB_DATABASE=replora_test and refreshes it on every run. Create that database next to your development one. Never point the tests at a database whose data you want to keep.
Working on the tracker
- Source:
packages/tracker/src(index.tsstarts everything;api.tsthe command queue;signals.tserrors, console, network, clicks;forms.ts,surveys.ts,experiments.ts,editor.ts,crossdomain.ts,rules.ts,unmask.ts,visitor.ts,canvas.ts,frames.ts,ga.ts,diagnostics.ts). - Every file has its
*.test.ts(jsdom); coverage must stay at 100 %. - Never let an error reach the host page: wrap work in
try/catch, as the existing code does. - The output lands in the Recordings module; commit it with the source change.
