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.

`just install` - Dependency Installation¶

The just install command installs npm dependencies for all 5 frontend packages sequentially:

frontend/
├── 1. shared/         → npm install
├── 2. widget/         → npm install
├── 3. preprod-ui/     → just install → npm install
├── 4. chrome-plugin/  → npm install
└── 5. client-backoffice/ → just install → npm install

Why Nested Justfiles?¶

Two packages (preprod-ui and client-backoffice) have their own justfile with an install command. This allows:

Standalone installation: Each package can be installed independently
Future flexibility: Additional setup steps can be added per-package
Consistency: Running just install works the same whether in root or subdirectory

Source Code¶

From frontend/justfile:

install:
    @echo "Installing dependencies for all projects..."
    @cd shared && echo "Installing shared dependencies..." && npm install
    @cd widget && echo "Installing widget dependencies..." && npm install
    @cd preprod-ui && echo "Installing preprod-ui dependencies..." && just install
    @cd chrome-plugin && echo "Installing chrome-plugin dependencies..." && npm install
    @cd client-backoffice && echo "Installing client-backoffice dependencies..." && just install
    @echo "All dependencies installed successfully!"

`just dev` - Development Server¶

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

just dev
├── 1. _build-shared: Build shared package (one-time compilation)
│   └── cd shared && just build
└── 2. cd preprod-ui && just dev
    ├── Check .env.test exists (fails if missing)
    ├── Build preprod-ui 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 Preprod UI Dev Environment

The preprod-ui/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 preprod-ui 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 preprod UI (recommended)
`just dev-shared`	Watch shared package only
`just dev-preprod`	Start preprod UI only (assumes shared is built)
`just dev-client-backoffice`	Build shared + start client backoffice

Why `.env.test` is Required¶

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

preprod-ui/justfile:

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

client-backoffice/justfile:

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

The preprod-ui dev command explicitly checks for this file:

# _check-env-test task in preprod-ui/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 (preprod-ui, 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
`just install`	Install dependencies for all packages
`just download-env all`	Download all environment files
`just clean`	Remove all `dist/` directories

Development¶

Command	Description
`just dev`	Build shared + start preprod UI
`just dev-shared`	Watch shared package only
`just dev-preprod`	Start preprod 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-preprod-ui`	Build preprod UI only
`just build-chrome-plugin`	Build Chrome extension
`just build-client-backoffice`	Build client backoffice

Testing¶

Command	Description
`just test`	Run unit tests
`just test integration`	Run integration tests
`just test coverage`	Run tests with coverage
`just test watch`	Run tests in watch mode
`just type-check`	Type check all projects
`just e2e`	Run E2E tests with Playwright
`just e2e ui`	Run E2E tests with interactive UI

Deployment¶

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

Utilities¶

Command	Description
`just gen-types`	Generate Supabase TypeScript types
`just diff-env all`	Compare local vs remote env files