Skip to content

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).

20 minutesDevelopersSingle user · SaaS

Requirements ​

ToolVersion
Node.js22 recommended (engines: ^20.19.0 or >=22.12.0)
pnpm10 (the repository pins [email protected] through packageManager; corepack enable picks it up)
PHP8.3 or newer, with pdo_pgsql, mbstring, openssl, zlib, zip, sodium, fileinfo (and pcov for coverage)
Composer2
PostgreSQL13 or newer
RedisOptional (cache, queue); the database works too
DockerOptional, 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 development

Set up a development copy ​

  1. Start the services (or use your own PostgreSQL):

    sh
    docker compose up -d
    ServiceAddressCredentials
    PostgreSQL 17127.0.0.1:5433, database replorareplora / secret
    Redis 7127.0.0.1:6380—
    MinIO (S3)API 127.0.0.1:9002, console 127.0.0.1:9003, bucket recordingsreplora / replora-secret

    The ports are shifted by one so they don't collide with services already running on your machine.

  2. Install the JavaScript dependencies (the whole workspace):

    sh
    pnpm install
  3. Install the PHP dependencies and configure the app:

    sh
    cd apps/standalone
    composer install
    cp .env.example .env
    php artisan key:generate

    The repository's .env.example is the developer template (local services above, debug on, REPLORA_MODE=single). Set REPLORA_MODE=saas to work on the SaaS edition. See Environment.

  4. Install: open the app and use the web installer, or run it on the command line:

    sh
    REPLORA_LICENSE_REQUIRED=false php artisan replora:install --url=http://127.0.0.1:8010 --skip-license

    --skip-license works only while REPLORA_LICENSE_REQUIRED is false and every module is present (true in a development copy); otherwise the installer asks for a purchase code. Alternatively set REPLORA_INSTALLED=true in .env, run php artisan migrate and create an administrator with php artisan replora:admin.

  5. Build and run:

    sh
    cd ../..        # 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 queue

    For 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 ​

StepCommandOutput
1. Offline playernode tools/offline-player.mjsmodules/Recordings/Resources/offline/player.{js,css}: the player embedded in downloaded recordings
2. Trackerpnpm --filter @replora/tracker run build (esbuild, ES2019, IIFE, minified)modules/Recordings/Resources/tracker/t.js, served at /t.js
3. npm packagespnpm run build:packages (TypeScript)packages/browser/dist, packages/react/dist
4. Dashboardpnpm --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 buildEverything above
pnpm build:trackerOnly t.js
pnpm --filter @replora/tracker run watchRebuilds t.js on every change (with an inline source map)
pnpm build:packagesOnly @replora/browser and @replora/react
pnpm devVite dev server for the dashboard
pnpm testAll Vitest tests (UI kit, tracker, npm packages, dashboard logic)
pnpm test:coverageThe same with coverage; fails below 100 % lines, functions, statements and branches
pnpm typecheckTypeScript of the tracker, both npm packages and the dashboard
pnpm i18ntools/check-i18n.mjs: every interface text translated in every language
pnpm i18n:writeAdds 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 i18n

Coverage 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
StepFails when
tools/check-imports.phpA PHP file uses a fully-qualified class name inline instead of a use import
tools/check-docs.phpA class, interface, trait or enum in app/, modules/ or saas/, or one of its public methods, has no PHPDoc
tools/check-modules.phpA module uses another module's classes, a module.json doesn't match its folder, or shared code names a SaaS module
vendor/bin/pint --testCode style differs from Pint's (vendor/bin/pint fixes it)
PHPUnit with PCOVA test fails
tools/check-coverage.php … 100Any 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.ts starts everything; api.ts the command queue; signals.ts errors, 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.

Replora: see what your visitors see.