Frontend Justfile Details¶

This document provides detailed information about the frontend justfile commands, what they do internally, and how to troubleshoot common issues.

For quick setup instructions, see Frontend Setup.

Dependency installation¶

Run npm install from frontend/, the npm workspace root. Do not run it inside members or introduce nested package lockfiles. See Frontend Setup.

The legacy just install recipe currently installs root tooling, then traverses member justfiles. That implementation is not the recommended dependency-editing procedure; use root npm for changes to the workspace dependency graph.

`just dev` - Development Server¶

The default just dev command runs the playground UI development environment:

just dev
├── 1. _build-shared: Build shared package (one-time compilation)
│   └── cd shared && just build
└── 2. cd playground && just dev
    ├── Check .env.test exists (fails if missing)
    ├── Build playground with test config
    └── Start two parallel processes:
        ├── cd ../shared && npm run dev  (watch mode)
        └── npm run dev                   (Vite dev server)

Execution Details¶

Step 1: Build Shared Package

cd shared && just build

Compiles the shared package so other packages have access to the built dependencies. This runs once at startup.

Step 2: Run playground UI Dev Environment

The playground/justfile dev command:

Validates environment - Checks .env.test exists in frontend/
Builds for test - Generates version.json and builds with test config
Starts shared in watch mode - Background process watching for changes in shared/
Starts Vite dev server - Background process serving playground with hot reload

Both processes run in parallel. Ctrl+C cleanly stops both via signal handlers.

All Dev Commands¶

Command	Description
`just dev`	Build shared + start playground UI (recommended)
`just dev-shared`	Watch shared package only
`just dev-playground`	Start playground UI only (assumes shared is built)
`just dev-client-backoffice`	Build shared + start client backoffice

Why `.env.test` is Required¶

Both playground and client-backoffice load .env.test automatically via their justfiles:

playground/justfile:

set dotenv-filename := "../.env.test"

client-backoffice/justfile:

set dotenv-path := "../.env.test"

The playground dev command explicitly checks for this file:

# _check-env-test task in playground/justfile
if [ ! -f ../.env.test ]; then
    echo "❌ Error: .env.test file is missing in @frontend/ directory!"
    echo "Please run: cd .. && just download-env test"
    exit 1
fi

Environment Files¶

Available Environments¶

File	Secret Name	Used By
`.env.production`	`rose-frontend-env-production`	Production builds
`.env.staging`	`rose-frontend-env-staging`	Staging builds
`.env.test`	`rose-frontend-env-test`	Dev servers (playground, client-backoffice)
`.env.development`	`rose-frontend-env-development`	Development builds

Environment Variables¶

The .env files contain (from .env.example):

# API Configuration
IX_API_KEY=
IX_API_URL=

# Supabase Configuration (Required)
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=
VITE_ENVIRONMENT=

# PostHog Analytics
VITE_PUBLIC_POSTHOG_KEY=
VITE_PUBLIC_POSTHOG_HOST=

# Sentry Error Tracking
VITE_SENTRY_DSN=

# Snitcher Radar
VITE_SNITCHER_PROFILE_ID=

Environment Commands¶

Command	Description
`just download-env all`	Download all 4 environment files
`just download-env test`	Download only `.env.test`
`just download-env production`	Download only `.env.production`
`just upload-env <env>`	Upload local env file to Secret Manager
`just diff-env all`	Compare local vs remote env files

Troubleshooting¶

"Error: .env.test file is missing"¶

cd frontend
just download-env test
# or download all environments
just download-env all

"Secret not found" or permission errors¶

# 1. Authenticate
gcloud auth login
gcloud auth application-default login

# 2. Setup secret access (one-time)
cd backend
just setup-secrets

# 3. Test access
just test-secrets

# 4. Try downloading again
cd ../frontend
just download-env all

Check which env files exist locally¶

ls -la frontend/.env.*

Compare local vs remote env files¶

cd frontend
just diff-env all

Complete Command Reference¶

Installation & Setup¶

Command	Description
`npm install`	Install dependencies from the frontend workspace root
`just download-env all`	Download all environment files
`just clean`	Remove all `dist/` directories

Development¶

Command	Description
`just dev`	Build shared + start playground UI
`just dev-shared`	Watch shared package only
`just dev-playground`	Start playground UI only
`just dev-client-backoffice`	Build shared + start client backoffice

Building¶

Command	Description
`just build`	Build all projects (CI-safe)
`just build-all`	Build all including chrome-plugin
`just build-widget`	Build widget only
`just build-playground`	Build playground UI only
`just build-chrome-plugin`	Build Chrome extension
`just build-client-backoffice`	Build client backoffice

Testing¶

Command	Description
`npm run test:unit`	Run unit tests
`npm run test:integration`	Run integration tests
`npm run test:coverage`	Run tests with coverage
`npm run test:watch`	Run tests in watch mode
`just type-check`	Type check all projects
`just lint`	Biome, import boundaries, and TypeScript
`just check`	Lint, TypeScript, and unit tests
`just test-projects shared widget`	Unit tests for selected projects
`just e2e`	Run E2E tests with Playwright
`just e2e ui`	Run E2E tests with interactive UI

Run from frontend/. just test also runs unit tests; just test integration, just test coverage, and just test watch select the corresponding npm scripts.

Deployment¶

Command	Description
`just deploy-playground`	Deploy playground UI to Firebase
`just preview-playground`	Preview deployment (test channel)

Utilities¶

Command	Description
`just gen-types [target]`	Defaults to production; optional `local` or hosted project ref; see type generation
`just diff-env all`	Compare local vs remote env files