Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
325 lines (223 loc) · 9.67 KB

CONTRIBUTING.md

File metadata and controls

325 lines (223 loc) · 9.67 KB
Raw

Contributing to Fluxora Frontend

Thanks for contributing to Fluxora. This guide covers everything you need to go from zero to a mergeable PR: local setup, branch naming, commit conventions, and the full test/coverage workflow.

Quick Start Checklist

For first-time contributors:

  • Fork the repo and clone your fork
  • Run npm install to install dependencies
  • Copy .env.example to .env.local and fill in required values
  • Run npm run dev to start the local dev server
  • Create a branch: feat/<issue>-short-description or fix/<issue>-short-description
  • Make your change and write/update tests
  • Run npm test and npm run lint before pushing
  • Open a PR targeting main and fill out the template

Table of Contents

  1. Prerequisites
  2. Local Setup
  3. Environment Variables
  4. Branch Naming
  5. Commit Conventions
  6. Development Workflow
  7. Testing
  8. Lint and Format
  9. Design Specs and Docs
  10. Pull Request Expectations
  11. Security Notes

Prerequisites

  • Node.js 18 or later
  • npm (bundled with Node) or pnpm
  • Git

For end-to-end tests you also need Playwright browsers installed (see E2E Tests).

Local Setup

# 1. Clone and enter the repo
git clone https://github.com/Fluxora-Org/Fluxora-Frontend.git
cd Fluxora-Frontend

# 2. Install dependencies
npm install
# or: pnpm install

# 3. Copy the environment file
cp .env.example .env

# 4. Start the dev server
npm run dev
# or: pnpm run dev

The app runs at http://localhost:5173.

Environment Variables

All runtime config lives in .env (gitignored). Copy .env.example as shown above, then set the values you need.

Variable Required at runtime Purpose
VITE_API_URL For live API calls Backend base URL
VITE_NETWORK For wallet validation TESTNET (default) or PUBLIC
VITE_RPC_URL For on-chain transactions Soroban RPC endpoint
VITE_STREAM_CONTRACT_ID For on-chain streaming Deployed contract address (C…)
VITE_USE_MOCKS No true enables mock data paths
VITE_DEMO_MODE No true renders static fixture data
VITE_TX_POLL_INTERVAL_MS No Transaction polling interval (ms, default 750)
VITE_TX_POLL_MAX_ATTEMPTS No Max polling attempts (default 6)
VITE_TX_POLL_BACKOFF_FACTOR No Exponential backoff multiplier (default 1.25)
VITE_TX_DEMO_CONFIRMATION_ATTEMPTS No Mock confirmation cycles (default 2)

For full documentation of each variable, see docs/environment.md.

Tip for local development: Set VITE_USE_MOCKS=true in your .env to run the full UI without a live backend or wallet.

Branch Naming

Use this pattern:

<type>/<short-kebab-description>

Common types mirror the commit types below:

Type When to use
feat New feature or UI component
fix Bug fix
docs Documentation only
refactor Code restructure with no behaviour change
test Adding or updating tests
chore Tooling, deps, config changes
ci CI/CD workflow changes

Examples:

feat/stream-cancel-button
fix/wallet-disconnect-race
docs/contributing-guide
test/metric-card-coverage

Commit Conventions

This repo follows Conventional Commits.

<type>(<optional scope>): <short summary>

<optional body — what and why, not how>

<optional footer — e.g. Closes #123>

Rules:

  • Use the imperative mood in the summary: "add X", not "added X".
  • Keep the summary line under 72 characters.
  • Reference the relevant GitHub issue in the footer when applicable: Closes #390.
  • Do not mix unrelated changes in a single commit.

Examples:

feat(streams): add cancel stream confirmation modal

Closes #201

fix(wallet): clear stale address on Freighter disconnect

Prevents the app shell from showing a connected state after
the extension removes the session.

Closes #312

docs: add contributing guide

Covers setup, branch naming, commit conventions, and the
test/coverage workflow for new contributors.

Closes #390

Development Workflow

# Run the dev server
npm run dev

# Production build (type-check + bundle)
npm run build

# Preview the production build locally
npm run preview

# Bundle size report (runs build first)
npm run build:report

Testing

Unit Tests

Vitest runs all *.test.tsx / *.test.ts files under src/, excluding e2e/.

# Single run (used in CI)
npm run test

# Watch mode (local development)
npm run test:watch

Coverage

The CI coverage job enforces 95% thresholds across statements, branches, functions, and lines. Run this locally before opening a PR:

npm run test:coverage

The report is written to coverage/ (HTML) and printed to the terminal. If your branch adds a new production module, append it to the include list in vitest.config.ts and add tests to cover it — otherwise the coverage job will fail.

E2E Tests

Playwright drives the browser-level tests in e2e/. Install browsers once:

npx playwright install --with-deps

Then run:

# Full e2e suite (starts the dev server automatically)
npm run test:e2e

# Accessibility-only suite
npm run test:a11y

Playwright auto-starts npm run dev on port 5173 before the suite and tears it down after. Set PLAYWRIGHT_BASE_URL to point at a different server if needed.

Lint and Format

# Check for lint errors
npm run lint

# Auto-fix lint errors where possible
npm run lint:fix

# Format source files
npm run format

# Check formatting without writing
npm run format:check

The repo uses ESLint flat config with TypeScript, React Hooks, and React Refresh rules. Prettier handles formatting for src/**/*.{ts,tsx,css} and top-level config files.

Both lint and format:check run in CI. Fix all warnings before pushing — the build fails on lint errors.

Design Specs and Docs

Several design and accessibility specs live at the repo root and in docs/. Refer to them when working on UI components:

File Topic
DESIGN_SPEC.md Visual design system
DESIGN_TOKENS_QUICK_REFERENCE.md Token reference
DARK_THEME_SPEC.md Dark mode behaviour
FOCUS_RING_SPEC.md Focus ring standards
WALLET_FLOWS_DESIGN_SPEC.md Wallet UX flows
STREAM_CARD_INTERACTION_SPEC.md Stream card interactions
EMPTY_STATES_DESIGN_SPEC.md Empty state patterns
LOADING_SKELETON_DESIGN_SPEC.md Loading skeleton patterns
MODAL_FOCUS_MANAGEMENT_DESIGN_SPEC.md Modal focus management
docs/environment.md All VITE_* variables
docs/security.md Contract security model
docs/soroban-contract-abi.md Contract ABI reference

Pull Request Expectations

  • Fill in the PR template completely.
  • Every PR must pass the full CI matrix before merge:
    • npm run build — TypeScript type check + production bundle
    • npm run test — all unit tests green
    • npm run test:coverage — all coverage thresholds ≥ 95%
    • npm run lint — no lint errors
  • Link the related issue in the PR description and in the commit footer (Closes #<number>).
  • Keep PRs focused. One concern per PR makes review faster.
  • Add or update tests for every behaviour change. See Coverage.

Security Notes

  • VITE_* variables are public. Vite statically inlines them into the client bundle at build time. Anyone can read them by inspecting the page source or network traffic. Never put secrets, private keys, seed phrases, wallet credentials, or sensitive API tokens in .env or .env.local.
  • Private secrets belong on the backend (fluxora-backend). The frontend only holds public metadata: RPC endpoints, contract IDs, network identifiers, and feature flags.
  • Address inputs are sanitized through sanitizeStellarAddress before reaching explorer links, the clipboard, or query strings.
  • The /app route subtree is protected by RequireWallet. This is a client-side UX guard only — backend services must still enforce authorization independently.

For the full contract security model see docs/security.md.

Bundle Size Thresholds

Vite is configured with a chunk size warning limit of 650 kB (chunkSizeWarningLimit in vite.config.ts). A CI job enforces this as a hard gate:

# Run locally before opening a PR:
npm run size-check

This runs npm run build followed by node scripts/bundle-size-report.mjs --fail, which exits with code 1 if any JS chunk exceeds 650 kB, blocking the merge.

Temporarily exempting a chunk

If you need to merge while a chunk is over-limit (e.g. a large vendored library with no tree-shaking support), pass --allow <chunkName> in the CI step and add a comment explaining the reason and a follow-up ticket:

# .github/workflows/bundle-size-check.yml
run: npm run build && node scripts/bundle-size-report.mjs --fail --allow vendor-heavy
# TEMP: vendor-heavy does not support ESM tree-shaking. Tracked in #999.

Remove the exemption once the underlying issue is resolved.