Frontend Monorepo

A monorepo for all our frontend apps, designed to simplify sharing of code like components, styles, utils, and configs between different applications.

Technology Stack

• Turborepo: For monorepo management and build tooling
• PNPM: Our package manager
• TypeScript: Our main language with shared, extendable config
• NextJS: The framework for all our frontend apps
• Tailwind CSS: For styling
• shadcn/ui: Our UI component base library to extend from
• Trunk CLI: Metalinter and formatter (ESLint, Prettier, Markdown, YAML, Shell, Commitlint)
• Vercel: For deployments and turborepo build remote caching
• GitHub Actions: For CI (with Turborepo caching for builds via Vercel)

Repo Structure

frontend-monorepo/
├── apps/                     # Frontend applications
│   ├── app.mento.org/        # Mento Exchange UI
│   ├── governance.mento.org/ # Governance UI
│   ├── reserve.mento.org/    # Reserve UI
│   └── ui.mento.org/         # Component Library Showcase
│
├── packages/                 # Shared packages
│   ├── eslint-config/        # Shared ESLint configuration
│   ├── typescript-config/    # Shared TypeScript configuration
│   ├── ui/                   # Shared UI library with tailwind styles and shadcn/ui components
│   ├── vitest-config/        # Shared Vitest configuration
│   └── web3/                 # Shared library with web3-specific components and hooks
│
├── .github/                  # GitHub workflows
│   └── workflows/            # CI/CD workflows
├── .trunk/                   # Trunk CLI configuration and cache
├── docs/
│   └── adr/                  # Architecture decision records and lifecycle
├── turbo.json                # Turborepo configuration
└── pnpm-workspace.yaml       # PNPM workspace configuration

Getting Started

Prerequisites

• Node.js (v22 or later)
• PNPM (v10 or later)
• Trunk CLI (automatically installed during development)

Installation

1. Clone the repository:

   git clone https://github.com/mento-protocol/frontend-monorepo && cd frontend-monorepo
   

2. Install dependencies:

   pnpm install
   

3. Configure environment variables for each app you plan to build or run:

   cd apps/<app-name>
   cp .env.example .env.local
   

4. Build all packages:

   pnpm build
   

5. Start the development server for all applications:

   pnpm dev
   

Environment Variables

Each app has its own .env.example listing the variables it needs:

• apps/app.mento.org/.env.example
• apps/governance.mento.org/.env.example
• apps/reserve.mento.org/.env.example
• apps/ui.mento.org/.env.example

For each app you run locally, copy its example file to .env.local and fill in the values before building or starting dev:

cd apps/<app-name>
cp .env.example .env.local

Most values are public config and safe to copy as-is. A few require secrets from a teammate or the Vercel project settings:

• app.mento.org needs NEXT_PUBLIC_STORAGE_URL and NEXT_PUBLIC_WALLET_CONNECT_ID; its sanctions check needs no key, only outbound access to OFAC's Sanctions List Service
• governance.mento.org needs NEXT_PUBLIC_WALLET_CONNECT_ID, NEXT_PUBLIC_GRAPH_API_KEY, and ETHERSCAN_API_KEY
• reserve.mento.org needs NEXT_PUBLIC_STORAGE_URL and NEXT_PUBLIC_ANALYTICS_API_URL
• ui.mento.org needs NEXT_PUBLIC_STORAGE_URL for showcase static assets

Development Workflow

Code Quality & Formatting

We use Trunk CLI as our universal linter and formatter. It combines ESLint, Prettier, Markdown linting, YAML linting, and more into a single, fast tool.

Available Commands

# Lint all files (comprehensive check)
pnpm lint

# Lint with auto-fix
pnpm lint:fix

# Format all files
pnpm format

# Check formatting without making changes
pnpm format:check

# Verify every third-party GitHub Action uses an immutable SHA + version comment
pnpm ci:action-pins

# Run the action-pin scanner and REST materializer fixture suites
pnpm ci:action-pins:test

# Test the native Dependabot schedule, grouping, and dependency policy
pnpm dependency:policy:test

# Remind on newly added architecture-significant workflows/workspaces
pnpm adr:check

# Test the offline ADR reminder and repository wiring
pnpm adr:check:test

# Test the network-free Vercel planning and prebuilt-build primitives
pnpm vercel:primitives:test

# Test canonical read-only Vercel state and guarded alias-drift evidence
pnpm vercel:deployment-state:test

# Test Vercel preview and main workflows, exact-main gating, transactions, and smoke
pnpm vercel:workflow:test

# Test preview state, reusable smoke trust, native-adapter, and Git ownership
pnpm vercel:preview:test

# Test the staged-candidate toolkit and shared candidate-build actions
pnpm vercel:production-shadow:test

# Verify exact Next.js and Vercel CLI custom deployment-ID prerequisites
pnpm vercel:versions:check

Two always-run checks protect the policy on every pull request: GitHub Actions Policy runs the trusted base-branch checker against only the PR head's Actions YAML, fetched as inert blobs from its exact commit through the GitHub Git API. It never checks out or executes pull-request files. GitHub Actions Policy Source runs the proposed checker, REST materializer, and fixtures in a credential-free pull_request workflow. After these workflows merge, branch protection must require both Action Pin Policy and Action Pin Policy Source so neither trusted enforcement nor proposed-policy validation can be skipped. Because the source lane necessarily runs pull-request-controlled policy code, changes to either policy workflow, checker, or fixture suite must also require protected human/code-owner review or an organization required-workflow rule; the two status contexts alone are not a tamper-proof approval boundary. Canonical structure changes such as pnpm/Node versions, commands, or triggers intentionally require a protected two-PR transition. The first pull request teaches the trusted checker to allow the transition while the workflows and root package-manager declaration stay unchanged. For a pnpm transition, the checker accepts only the paired old or paired target workflow versions. The second pull request changes the root declaration and both workflow pins together, then tightens the checker to the target version. A mixed workflow pair is invalid. An explicit workflow version that differs from the root packageManager value also makes pnpm/action-setup fail before the checker runs. Require both Action Pin Policy checks on each stage's exact head and base. Revalidate after any head or base change. Immutable action SHA bumps are normalized by the checker and can remain a single PR. When adding or updating a third-party action, pin its full 40-character commit SHA and retain the release tag as an inline comment (for example, uses: org/action@<sha> # v1.2.3).

App-Specific Linting

To lint a specific application:

cd apps/<app-name>
pnpm lint                    # Lints only this app

Or from the root directory:

trunk check apps/<app-name>  # Direct Trunk usage

What Trunk Checks

• JavaScript/TypeScript: ESLint with your existing rules
• Code Formatting: Prettier (including Tailwind CSS class sorting)
• Markdown: Documentation formatting and best practices
• YAML: Configuration file formatting
• Shell Scripts: shellcheck and shfmt
• Git: Pre-commit and pre-push hooks

VS Code Integration

The workspace is configured to use Trunk for:

• Auto-formatting on save for JS/TS files
• Lint-on-type feedback
• Code actions for quick fixes

Running a Single Application

To run a specific application:

cd apps/<app-name>
pnpm dev

Or from the root directory:

pnpm dev --filter <app-name>
# i.e. pnpm dev --filter ui.mento.org

Building a Single Application

To build a specific application:

pnpm build --filter <app-name>

Local Celo fork

For wallet-gated testing against real Mento contracts, run a local anvil fork of Celo mainnet:

pnpm fork:mainnet  # anvil --celo --auto-impersonate --fork-url https://forno.celo.org --port 8545
pnpm fork:seed     # fund anvil's junk accounts (CELO + cUSD/cEUR/USDC/MENTO) and re-report oracle prices (mainnet forks only)
pnpm fork:testnet  # same anvil flags, forking Celo Sepolia instead (fork:seed does not support testnet forks)

--celo requires Foundry >= 1.4 — without it, CELO's native/ERC-20 token duality breaks and transfer() silently no-ops. fork:seed selects an FX-open fork timestamp with two hours of runway before it reports oracles. During a weekend or year-end closure, the fork can run ahead of the runner clock. A second seed preserves that safe timestamp. Re-run it after every evm_revert and whenever Broker quotes start reverting because SortedOracles reports expire.

Local Monad fork

Monad mainnet (chain 143) runs a different Mento stack than Celo (Router + FPMM, no Broker), so it has its own scripts and port:

pnpm fork:monad       # anvil --auto-impersonate --fork-url https://rpc.monad.xyz --fork-block-number <finalized> --port 8546 (no --celo)
pnpm fork:seed:monad  # fund anvil's junk accounts with MON + Reserve collateral + every Mento stable (via real Router swaps), re-report oracles

fork:seed:monad uses the same FX-open clock policy as the Celo seed. Its raw seeding swaps derive deadlines from the fork block timestamp, so a future safe timestamp does not expire them. The command is idempotent; re-run it after every evm_revert or when quotes stall. To point the app at this fork, dev/build with NEXT_PUBLIC_MONAD_RPC_URL=http://localhost:8546 — Monad has no --celo/NEXT_PUBLIC_USE_FORK redirect, so that override is the seam (it redirects both wagmi and the mento-sdk). See docs/wallet-testing.md for the full Monad runbook.

Full runbook with localStorage activation, on-chain verification, safety rules, and troubleshooting: docs/wallet-testing.md

Dependency Management with PNPM Catalog

This monorepo uses PNPM's catalog feature to centralize dependency version management. This ensures all packages and apps use consistent versions of shared dependencies, reducing conflicts and simplifying updates.

How It Works

The catalog is defined in pnpm-workspace.yaml under the catalog section. Instead of specifying version numbers directly in each package.json, we reference the catalog using "catalog:".

Example in package.json:

{
  "dependencies": {
    "react": "catalog:",
    "jotai": "catalog:",
    "@tanstack/react-query": "catalog:"
  }
}

The actual versions are defined once in pnpm-workspace.yaml:

catalog:
  "react": ^19.2.5
  "jotai": ^2.16.2
  "@tanstack/react-query": 5.90.16

Root pnpm.overrides are used for security patches and compatibility pins. @tanstack/react-query and @tanstack/query-core are pinned there to the verified app-compatible version; newer compatible-range releases caused a production QueryClient context split in app.mento.org. Remove those overrides only after a production build and browser verification of the swap and pools routes. Note the catalog entry above matches the override exactly (5.90.16, not a caret range) — pnpm overrides rewrite catalog: references too, so the catalog value must stay truthful about what's actually installed. See docs/dependency-overrides.md for the reason and removal condition behind every unconditional override.

Adding a New Dependency

When adding a new dependency that should be shared across packages:

1. Add the dependency to the catalog in pnpm-workspace.yaml:

   catalog:
     "new-package": ^1.0.0
   

2. Reference it in your package.json:

   {
     "dependencies": {
       "new-package": "catalog:"
     }
   }
   

3. Run pnpm install to update the lockfile.

Updating a Dependency Version

To update a dependency version across the entire monorepo:

1. Update the version in pnpm-workspace.yaml:

   catalog:
     "react": ^19.2.0 # Updated from ^19.1.0
   

2. Run pnpm install to update all packages using this dependency.

All packages referencing "react": "catalog:" will automatically use the new version.

Dependabot preparation

Dependabot creates native npm and GitHub Actions PRs every second Monday at 06:00 UTC. The shared dependabot-prep skill prepares them, and each writer holds a claim in refs/mento-claims/v1/pr/<number> before it writes to a PR. Human approval, answered-thread resolution and merge remain with the maintainer, and Dependabot CI remains secretless. The two facts the skill takes from this repository, the batch budget and the technical reviewer, are in AGENTS.md; see ADR 0012.

When to Use Catalog vs Direct Versions

• Use catalog ("catalog:"): For dependencies shared across multiple packages/apps (React, TypeScript, common utilities, etc.)
• Use direct versions: For app-specific dependencies that aren't shared (e.g., a Next.js plugin only used in one app)

Working with Shared UI Components

The UI package is located in packages/ui/ and contains reusable components built with shadcn/ui.

Adding a New Component via shadcn/ui

shadcn/ui is our component base layer we extend from.

1. Install the shadcn/ui component you need: pnpm dlx shadcn@latest add button
2. Customize it to your needs by simply editing ./packages/ui/src/components/ui/button.tsx
3. Export the new component from the main barrel file ./packages/ui/src/index.ts
4. Build the UI package: pnpm build --filter @mento-protocol/ui

Adding a New Custom Component (without shadcn/ui)

1. Create a new component in packages/ui/src/components
2. Export it from packages/ui/src/index.ts
3. Build the UI package: pnpm build --filter @mento-protocol/ui

Using UI Components in Applications

Import components into an application:

// layout.tsx
import "@mento-protocol/ui/globals.css"; // Import once at the top of the app
import { Button } from "@mento-protocol/ui";

Using UI Components Outside This Monorepo

Install the public package once it has been manually published:

pnpm add @mento-protocol/ui

Import the bundled stylesheet once at the app root, then import components from the package entrypoint:

import "@mento-protocol/ui/globals.css";
import { Button } from "@mento-protocol/ui";

globals.css includes the Mento token layer, Tailwind-generated utilities, component styles, and the bundled unmodified Aspekta font. Consumers that only need the CSS variables and Tailwind v4 token declarations can import @mento-protocol/ui/theme.css instead. React and React DOM are peer dependencies; Tailwind CSS is an optional peer dependency unless the consuming app compiles or extends the package's Tailwind token layer.

Commit Convention

We use Conventional Commits for standardized commit messages. This helps with automated versioning and generating changelogs.

Each commit message should follow this format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types include:

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code changes that neither fix bugs nor add features
• test: Adding or fixing tests
• chore: Changes to the build process or auxiliary tools
• perf: Performance improvements

Example:

feat(ui): add new button component

Git Hooks: Trunk automatically manages git hooks that will:

• Pre-commit: Format and lint staged files
• Pre-push: Run comprehensive checks and the advisory pnpm adr:check reminder before pushing
• Commit-msg: Validate commit message format

CI/CD Pipeline

The repository is set up with GitHub Actions for CI:

• CI: On every PR, it plans the changed-file scope, fans build, two unit-test shards, and static analysis out in parallel, then reports the existing required Build and Test sentinel. The shards partition the root pnpm test command: Unit tests (workspaces) runs pnpm test:ci:workspaces (ADR, dependency-policy, and lockfile-lint suites plus the Turborepo workspace tests) and Unit tests (Vercel contracts) runs pnpm test:ci:vercel (the Vercel deployment contract suites). Sharding shortens CI's critical path, which is the point for PR feedback. The main deployment pipeline does not inherit that saving one-for-one: its own read-only pre-gate prefix runs about 187 seconds regardless of CI and floors when staging can start, so the deploy path inherits only whatever CI was above that floor. docs/vercel-deployments.md carries the measurement and the re-measure note. Markdown- and docs/**-only PRs skip builds, both unit shards, type checking, and Knip, but retain the Trunk static checks for Markdown validation and secret scanning. Scope-planning errors and all other PR paths fail closed into full validation. Every main push runs the full suite so a successful CI/CD workflow is trustworthy recovery evidence for the failure notifier.

• Quality budgets: The always-reported Quality Budgets check enforces production-source coverage and gzip route limits. Its general CI failure notifier opens or updates one issue for an operational workflow failure and closes the issue after recovery. The same failures also post to Slack's #ci-failures from .github/workflows/notify-slack-on-main-failure.yml, after a 15-minute recovery window. Reconciliation suppresses a recovered failure. Every sustained failure otherwise posts. The message links the run and the managed issue; run that workflow's workflow_dispatch from the Actions tab to smoke-test the Slack wiring.

• Dependabot preparation: Native updates open every second Monday at 06:00 UTC. The OpenClaw job on the scheduled host, run on the same cadence, prepares them with the shared dependabot-prep skill; the job owns its own schedule, prompt and Slack destination. No custom launcher and no repository policy file are required: the skill supplies the claim document. Every writer holds a per-pull-request claim ref before it writes, and one heavy process tree per host, rather than one active batch, caps the work. See , and .

Dependency-installing jobs use .github/actions/pnpm-install, which pins the Node/pnpm bootstrap, relies on actions/setup-node as the single pnpm-store cache owner, and enforces pnpm install --frozen-lockfile. Its optional filter input adds one --filter to that command; the default empty value installs every workspace project. Every vercel-main-deployment.yml job sets it to frontend-monorepo, and so does the secretless _vercel-preview-smoke.yml job, because their orchestration and smoke scripts need no app or package workspace; vercel-preview-controller.yml narrows its own raw pnpm --filter frontend-monorepo install the same way. Dependabot runs disable that cache and the Trunk action cache through the same positive repository-credential grant. Production-shadow candidate builds instead use the dedicated-UID .github/actions/vercel-candidate-build boundary documented in the deployment runbook; fresh browser-smoke jobs return to the trusted pnpm action. Publishing overrides the trusted composite's Node version and disables its cache; zero-dependency jobs may set up Node directly.

The docs-only decision is implemented by scripts/ci-change-plan.mjs and covered by pnpm ci:change-plan:test, which the Unit tests (workspaces) shard runs before its own suites. That suite also pins the shard partition itself: pnpm test must stay exactly pnpm test:ci:workspaces && pnpm test:ci:vercel, each CI shard must run exactly one of those scripts, the two must share no sub-suite, and both must carry the run_quality gate and feed the sentinel. The always-run sentinel accepts skipped build and unit test jobs only when that planner explicitly reports a documentation-only diff; the static-analysis job must always succeed. Its dependency-heavy type-check and Knip steps follow the planner, while Trunk remains mandatory for every diff. Failures, cancellations, unexpected skips, and invalid planner outputs remain blocking. Rename detection is disabled for the planning diff so both the old and new paths are classified; moving source into docs/** cannot masquerade as a documentation-only change. Markdown that tests assert on is still classified as documentation. Several unit suites read repository markdown and match phrases in it: scripts/dependency-policy.test.mjs reads AGENTS.md and CLAUDE.md; scripts/check-adr-reminder.test.mjs reads AGENTS.md, CLAUDE.md, README.md, and .github/pull_request_template.md; and the Vercel contract suites read docs/vercel-deployments.md. A documentation-only pull request skips both unit shards, so an edit to one of those files can land a stale assertion on main (#969 did on 2026-09-15; fixed in #970). Run pnpm test locally before pushing such a change. Until the target branch contains a trusted planner (including the workflow's bootstrap PR), CI runs the full quality suite instead of executing planner code from the pull-request checkout. Default-branch pushes also bypass changed-file planning and always run the full build, unit-test, type-check, Knip, and Trunk suite before CI/CD can report a successful recovery.

Trunk in CI

The CI pipeline uses the Trunk GitHub Action to:

• Install Trunk CLI in the CI environment
• Run the same linting and formatting checks as local development
• Save findings as a workflow artifact without giving PR code a write token
• Ensure consistent code quality across all environments

Turborepo Remote Caching

This repo utilizes Turborepo's Remote Caching, to speed up local development and CI/CD runs. It works by storing the outputs (build artifacts, logs) of tasks (like build, test, lint) in a shared remote cache on Vercel. Before running a task, Turborepo calculates a hash based on the input files, environment variables, and dependencies. If that hash exists in the remote cache, Turborepo downloads the stored output and logs instead of executing the task locally, saving a lot of time.

Local Development Remote Caching Setup

To connect your local machine to the remote cache:

1. Login to Vercel via Turbo CLI:

   pnpm dlx turbo login
   

   Follow the prompts to authenticate with your Vercel account.

2. Link the Repository:

   pnpm dlx turbo link
   

   This connects the local repository instance to your Vercel account/team's remote cache storage.

Once linked, turbo commands (like pnpm build, pnpm test) will automatically attempt to use the remote cache. You generally don't need to set TURBO_TOKEN or TURBO_TEAM locally after linking, as turbo stores the necessary credentials automatically.

CI/CD (GitHub Actions) Setup

The .github/workflows/ci.yml workflow is configured to automatically leverage remote caching:

• It uses the TURBO_TOKEN (a Vercel Access Token) and TURBO_TEAM (your Vercel team slug/ID) environment variables.
• These variables must be configured in the GitHub repository settings under Settings > Secrets and variables > Actions:
  • TURBO_TOKEN: As a Repository Secret.
  • TURBO_TEAM: As a Repository Variable.
• With these variables set, the CI runner can authenticate with Vercel to read from and write to the remote cache.

Signed Remote Caching

Signed Remote Caching is enabled ("signature": true in turbo.json). Artifacts are HMAC-signed with TURBO_REMOTE_CACHE_SIGNATURE_KEY before upload, and signatures are verified on download. This prevents cache poisoning: an attacker who steals TURBO_TOKEN (read/write API access) but not the signing key cannot inject malicious build artifacts.

The signing key is provisioned in:

• GitHub Actions, as the TURBO_REMOTE_CACHE_SIGNATURE_KEY Repository Secret.
• Each Vercel project (app.mento.org, governance.mento.org, reserve.mento.org, ui.mento.org) for production, preview, and development environments.

Local development: With signing enabled, both reads and writes require the key — a Turbo client without TURBO_REMOTE_CACHE_SIGNATURE_KEY cannot verify signatures on downloaded artifacts and treats every task as a remote-cache miss (it then runs the task locally and uses local cache normally). To get remote-cache hits locally, export the key in your shell with the same value used in CI:

export TURBO_REMOTE_CACHE_SIGNATURE_KEY="<value from a maintainer>"

Never commit the key. If you don't set it, nothing breaks — you just lose the remote-cache speedup.

Rotating the key: generate a new value (openssl rand -hex 64), then update all 13 locations in lockstep (1 GitHub secret + 4 projects × 3 envs). After rotation, the cache is effectively wiped — first build per task repopulates it.

Potential Future Improvements

• Add syncpack for consistent dependency versions across all monorepo packages (Now using PNPM catalog)

• Finetune builds. There's probably ways to make the builds of both packages and apps smaller and/or more performant.
• Make VS Code's "Go To Definition" on a component jump to the actual TypeScript source file instead of the compiled JS file in ./dist
• Enable additional Trunk linters for production CI (security scanning, image optimization)