From 324a015023f75674bf16d2502f4365dea2dcc4aa Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 09:08:53 -0300 Subject: [PATCH 01/10] add contributing guide draft --- CONTRIBUTING.MD | 359 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 357 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 1def665708..258cf4011a 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -1,3 +1,358 @@ -# How to contribute +# Contributing to Freighter -Please read the [Contribution Guide](https://github.com/stellar/.github/blob/master/CONTRIBUTING.md). \ No newline at end of file +Thank you for your interest in contributing to Freighter, the non-custodial +Stellar wallet browser extension. + +This guide covers everything you need to contribute to this repository. For the +Stellar organization's general contribution guidelines, see the +[Stellar Contribution Guide](https://github.com/stellar/.github/blob/master/CONTRIBUTING.md). + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Repository Structure](#repository-structure) +- [Development Setup](#development-setup) +- [Development Workflow](#development-workflow) +- [Code Style & Conventions](#code-style--conventions) +- [Testing](#testing) +- [Localization](#localization) +- [Pull Request Process](#pull-request-process) +- [Branching Strategy](#branching-strategy) +- [Release Process](#release-process) +- [Security Considerations](#security-considerations) +- [Getting Help](#getting-help) + +## Prerequisites + +- **Node.js** >= 22 (use `.nvmrc`: `nvm use`) +- **Yarn** v4.10.0 or newer +- **Chrome** or **Firefox** for testing the extension +- Familiarity with **TypeScript**, **React**, and browser extension architecture + +## Repository Structure + +Freighter is a **Yarn workspaces monorepo** with four main areas: + +``` +freighter/ +├── extension/ # Browser extension (popup, background, content script) +├── @stellar/freighter-api/ # Client SDK published to npm — used by dApps +├── @shared/ # Shared utilities (api, constants, helpers) +│ ├── api/ +│ ├── constants/ +│ └── helpers/ +├── docs/ # Docusaurus site (docs.freighter.app) +├── config/ # Shared build configs (Jest, Babel, Webpack) +└── .github/ + ├── workflows/ # 10 CI/CD workflows + └── agents/ # Playwright test AI agents +``` + +The extension itself has three runtime components: + +| Component | Location | Purpose | +| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------- | +| **Popup** | `extension/src/popup` | React app — the UI users see when clicking the extension icon | +| **Background** | `extension/src/background` | Service worker — account creation, data storage, signing, responds to popup/content script messages | +| **Content Script** | `extension/src/contentScript` | Listens for `@stellar/freighter-api` messages via `window.postMessage`, relays them to the background | + +## Development Setup + +### 1. Clone and install + +```bash +git clone https://github.com/stellar/freighter.git +cd freighter +nvm use # Switches to Node 22 +yarn setup # Installs dependencies and allows scripts +``` + +### 2. Configure environment + +Create `extension/.env`: + +```env +INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2-prd.stellar.org/api/v1 +``` + +### 3. Start development + +```bash +yarn start +``` + +This starts all workspaces in parallel: + +- `@stellar/freighter-api` — SDK build in watch mode +- `docs` — Docusaurus dev server on `localhost:3000` +- Extension dev server — popup on `localhost:9000` +- Extension build — outputs to `extension/build/` + +To start a single workspace: + +```bash +yarn start:extension # Extension only +yarn start:freighter-api # SDK only +yarn start:docs # Docs only +``` + +### 4. Load the extension in your browser + +**Chrome:** + +1. Navigate to `chrome://extensions` +2. Enable "Developer mode" +3. Click "Load unpacked" and select `extension/build/` + +**Firefox:** + +1. Navigate to `about:debugging#/runtime/this-firefox` +2. Click "Load Temporary Add-on" and select `extension/build/manifest.json` + +### 5. Hot reload caveats + +- **Popup changes** hot reload automatically via the dev server at + `localhost:9000` +- **Background/content script changes** require running `yarn build:extension` + and reloading the extension in the browser + +## Development Workflow + +### Common commands + +| Command | Purpose | +| ----------------------------------- | ---------------------------------- | +| `yarn start` | Start all workspaces (dev mode) | +| `yarn build` | Build all workspaces | +| `yarn build:extension` | Dev build of extension | +| `yarn build:extension:experimental` | Build with experimental features | +| `yarn build:extension:production` | Minified production build | +| `yarn test` | Run unit tests (watch mode) | +| `yarn test:ci` | Run unit tests (CI mode, no watch) | +| `yarn test:e2e` | Run Playwright e2e tests | + +### Dev server URLs + +| URL | Purpose | +| ----------------------------------- | ----------------------------------------- | +| `localhost:9000` | Extension popup (dev) | +| `localhost:9000/#/debug` | Blockaid debug panel | +| `localhost:9000/#/integration-test` | Integration test helper (clears app data) | +| `localhost:3000` | Documentation site | + +### Build variants + +- **Standard** (`yarn build:extension`) — for everyday development +- **Experimental** (`yarn build:extension:experimental`) — enables + feature-flagged features +- **Production** (`yarn build:extension:production`) — minified, security + guardrails enabled, cannot connect to dev server + +## Code Style & Conventions + +### Formatting & linting + +Code style is enforced automatically via pre-commit hooks. You rarely need to +run these manually: + +- **Prettier** formats code on commit (config: `.prettierrc.yaml`) +- **ESLint** fixes lint issues on commit (config: `eslint.config.js`) + +Key formatting rules: + +- Double quotes (`"`) +- 2-space indentation, no tabs +- Trailing commas everywhere +- 80-character line width +- Semicolons required + +### Pre-commit hooks + +On every commit, Husky runs: + +1. `pretty-quick --staged` — formats staged files +2. `lint-staged` — runs ESLint `--fix` on staged `.ts`/`.tsx` files +3. Translation build — auto-generates `extension/src/popup/locales/` files + +If using nvm, create `~/.huskyrc` to ensure the correct Node version loads for +hooks. + +### Navigation + +Use `navigateTo` from `popup/helpers/navigate` for all navigation. Use the +`ROUTES` enum from `popup/constants/routes` instead of hardcoded path strings. +See `extension/STYLEGUIDE.MD` for details. + +### Imports + +Organize imports with external packages first, then internal modules. ESLint +enforces this ordering. + +## Testing + +### Unit tests (Jest) + +```bash +yarn test # Watch mode +yarn test:ci # CI mode (no watch) +``` + +- Tests live in `__tests__/` directories alongside source files +- Environment: JSDOM (`jest-fixed-jsdom`) +- Coverage collected from `src/**/*.{ts,tsx,mjs}` + +### E2E tests (Playwright) + +```bash +yarn test:e2e # Run all tests +yarn test:e2e sendPayment.test.ts # Specific test file +yarn test:e2e --ui # Interactive UI mode +yarn test:e2e --headed # See the browser +yarn test:e2e -g "Send doesn't throw" # Run by test name +PWDEBUG=1 npx playwright test # Debug mode +``` + +**Configuration:** + +- Browser: Chromium only +- Viewport: 1280x720 +- Timeout: 15 seconds per test, 5 retries +- Workers: 8 locally, 4 on CI + +**Snapshot testing:** + +- Visual snapshots stored in `[testName].test.ts-snapshots/` +- Update baselines: `yarn test:e2e --update-snapshots` + +For the full e2e testing guide, see +[`extension/e2e-tests/README.md`](extension/e2e-tests/README.md). + +### Before submitting a PR + +- All unit tests must pass (`yarn test:ci`) +- Run relevant e2e tests for your change area +- CI runs both Jest and Playwright on every PR + +## Localization + +Freighter uses `react-i18next` for translations. See +[`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD) for the full guide. + +**Quick summary:** + +1. Wrap user-facing strings with the `t()` function from the `useTranslation` + hook +2. Add the key/value pair to all language JSON files in + `extension/src/popup/locales/` +3. Run `yarn build:extension:translations` to auto-generate missing keys + (defaults to English) + +Translation files are auto-built and staged on every commit via the pre-commit +hook. + +**Testing translations:** Change your browser language, clear the +`react-i18next` localStorage value, and refresh. + +## Pull Request Process + +### Branch naming + +Use prefixed branch names: + +| Prefix | Use | +| ---------- | --------------------------------- | +| `feature/` | New features | +| `fix/` | Bug fixes | +| `chore/` | Maintenance, refactoring, tooling | +| `bugfix/` | Alternative bug fix prefix | + +### Commit messages + +Start with an action verb in present tense. Keep the subject concise. + +``` +Add hardware wallet support for Trezor +Fix transaction signing for multi-sig accounts +Update Soroswap SDK to v2.0 +Improve asset list loading performance +``` + +### PR expectations + +- **Keep PRs focused** — don't mix refactoring with feature changes +- **Include screenshots or videos** for UI changes (before/after) +- **Self-review** your code before requesting review +- **Add tests** for new functionality +- **Test on both Chrome and Firefox** when touching extension behavior +- **Update translations** if adding user-facing strings (the pre-commit hook + handles generation) + +### CI checks + +Every PR triggers: + +- **Jest unit tests** + **Playwright e2e tests** (`runTests.yml`) +- **CodeQL** security analysis (`codeql.yml`) + +Your PR must pass all checks before merging. + +## Branching Strategy + +| Branch | Purpose | +| ------------------- | ----------------------------------------------------------- | +| `master` | Main development branch | +| `release` | Release candidate branch (auto-created by release workflow) | +| `emergency-release` | Hotfix branch for emergency patches | +| `v{X.Y.Z}` | Version branches created during release (e.g., `v5.39.0`) | + +All feature/fix branches are created from and merged back into `master`. + +## Release Process + +Releases are orchestrated via the `newRelease.yml` GitHub Actions workflow: + +1. **Trigger:** Manual dispatch with `appVersion` (e.g., `5.39.0`) and source + branch +2. **Automation:** Creates `release` and `v{VERSION}` branches, bumps versions + in `package.json` and `manifest.json`, generates release notes, creates a PR +3. **Submission workflows:** Separate workflows handle Chrome Web Store, Firefox + AMO, Safari, and npm publishing + +You generally don't need to worry about the release process unless you're a +maintainer. + +## Security Considerations + +Freighter handles private keys and signs transactions. When contributing, keep +these principles in mind: + +- **Never log or expose private keys**, seed phrases, or passwords — not even in + debug builds +- **Validate all data** coming from external sources (dApp messages via content + script, API responses) +- **Do not bypass** Content Security Policy (CSP) or weaken existing security + guardrails +- **Be careful with `window.postMessage`** — the content script is an attack + surface between dApps and the extension +- **Use production builds** (`yarn build:extension:production`) when testing + security-sensitive flows — production builds have additional guardrails +- **Report vulnerabilities** via the + [Stellar Security Policy](https://github.com/stellar/.github/blob/master/SECURITY.md) + — do not open public issues for security bugs + +## Getting Help + +- **Extension architecture:** See [`extension/README.md`](extension/README.md) + for the popup/background/content script model +- **Hardware wallet integration:** See + [`extension/INTEGRATING_HARDWARE_WALLET.MD`](extension/INTEGRATING_HARDWARE_WALLET.MD) +- **Soroswap integration:** See + [`extension/INTEGRATING_SOROSWAP.MD`](extension/INTEGRATING_SOROSWAP.MD) +- **API reference:** See interactive playgrounds at + [docs.freighter.app](https://docs.freighter.app) +- **E2E testing:** See + [`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) +- **Questions:** Open a + [GitHub Discussion](https://github.com/stellar/freighter/discussions) or reach + out on the [Stellar Developer Discord](https://discord.gg/stellardev) From 2f2b285f1a21c89fa922d0a325fb776bd20bf80e Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 11:35:24 -0300 Subject: [PATCH 02/10] add contributing guide with LLM setup section --- .claude/skills/freighter-dev-setup/SKILL.md | 145 +++++++ CONTRIBUTING.MD | 429 +++++++------------- README.md | 10 +- 3 files changed, 296 insertions(+), 288 deletions(-) create mode 100644 .claude/skills/freighter-dev-setup/SKILL.md diff --git a/.claude/skills/freighter-dev-setup/SKILL.md b/.claude/skills/freighter-dev-setup/SKILL.md new file mode 100644 index 0000000000..551d966e57 --- /dev/null +++ b/.claude/skills/freighter-dev-setup/SKILL.md @@ -0,0 +1,145 @@ +--- +name: freighter-dev-setup +description: + Check, install, and configure all prerequisites for Freighter extension + development. Use when a contributor says "set up my dev environment", "quick + setup", "check my setup", "what do I need to install", or encounters build + failures from missing dependencies. Also use when someone clones the repo for + the first time. +--- + +# Freighter Extension Dev Setup + +Evaluate the contributor's machine against all prerequisites for Freighter +(browser extension), install what's missing, and run the initial setup. + +## Step 1: Check all prerequisites + +Run every check below and collect results. Report all at once — don't stop at +the first failure. + +For each tool, try the version command first. If it fails (e.g., sandbox +restrictions), fall back to `which ` to confirm presence. + +```bash +# Node.js >= 22 +node --version 2>&1 || which node + +# nvm (needed for node version management — repo has .nvmrc) +command -v nvm 2>&1 || test -d "$HOME/.nvm" && echo "nvm found" + +# Corepack +corepack --version 2>&1 || which corepack + +# Yarn 4.10.0 +yarn --version 2>&1 || which yarn + +# Browser (at least one needed for testing the extension) +test -d "/Applications/Google Chrome.app" && echo "Chrome: found" || echo "Chrome: not found" +test -d "/Applications/Firefox.app" && echo "Firefox: found" || echo "Firefox: not found" + +# Playwright (for e2e tests — installed via yarn, just check availability) +npx playwright --version 2>&1 || echo "Playwright: will be installed via yarn" +``` + +## Step 2: Present results + +Show a clear summary: + +``` +Freighter Extension — Prerequisites Check +========================================== + Node.js v22.x.x >= 22 required OK + nvm found any OK + Corepack 0.x.x any OK + Yarn 4.10.0 4.10.0 required OK + Chrome found at least one browser OK + Firefox not found (Chrome is enough) OK + Playwright via yarn for e2e tests OK +``` + +## Step 3: Install missing tools + +Present the missing tools and ask the user: "I can install [list] automatically. +Want me to proceed?" + +If the user confirms, **run the install commands** for each missing tool. After +each install, re-check the version to confirm it succeeded. If an install fails, +report the error and continue with the next tool. + +If the user declines, skip to Step 4 and note the missing tools in the final +summary. + +**Auto-installable (run after user confirms):** + +| Missing tool | Install command | +| --------------- | ------------------------------------------------------------------------------------------------- | +| Homebrew | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` | +| nvm | `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh \| bash` | +| Node.js 22 | `nvm install 22` | +| Corepack + Yarn | `corepack enable && corepack prepare yarn@4.10.0 --activate` | +| Chrome | `brew install --cask google-chrome` | + +**Manual — guide the user:** + +- If using nvm, create `~/.huskyrc` so pre-commit hooks load the correct Node + version: + ```bash + export NVM_DIR="$HOME/.nvm" + [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" + ``` + +## Step 4: Run initial setup + +```bash +nvm use # Switch to Node 22 (.nvmrc) +yarn setup # Install deps + allow scripts +``` + +## Step 5: Configure environment + +Check if `extension/.env` exists. If not, create it with the required variables: + +```env +INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 +``` + +These are the public production endpoints — the only required variables for +local development. To run your own backend, see +[stellar/wallet-backend](https://github.com/stellar/wallet-backend). + +If `extension/.env` already exists, verify it has both `INDEXER_URL` and +`INDEXER_V2_URL` set. + +## Step 6: Verify + +```bash +yarn build:extension +``` + +If the build succeeds, tell the user they're ready: + +1. Run `yarn start` +2. Open `chrome://extensions` (or `about:debugging` in Firefox) +3. Load unpacked from `extension/build/` +4. The popup is at `localhost:9000` + +If the build fails, read the error and diagnose — common causes are missing +`.env` vars or wrong Node version. + +## Step 7: Summary + +At the end, produce a final summary: + +``` +Setup Complete +============== + Installed: [list of tools installed] + Configured: extension/.env with backend endpoints + + Ready to run: + 1. yarn start + 2. Load extension/build/ in Chrome (chrome://extensions > Load unpacked) + 3. Popup at localhost:9000 +``` diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 258cf4011a..cf42798720 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -1,358 +1,219 @@ # Contributing to Freighter -Thank you for your interest in contributing to Freighter, the non-custodial -Stellar wallet browser extension. +Non-custodial Stellar wallet browser extension. Monorepo with extension, client +SDK, shared utilities, and docs site. -This guide covers everything you need to contribute to this repository. For the -Stellar organization's general contribution guidelines, see the +For the Stellar organization's general contribution guidelines, see the [Stellar Contribution Guide](https://github.com/stellar/.github/blob/master/CONTRIBUTING.md). -## Table of Contents - -- [Prerequisites](#prerequisites) -- [Repository Structure](#repository-structure) -- [Development Setup](#development-setup) -- [Development Workflow](#development-workflow) -- [Code Style & Conventions](#code-style--conventions) -- [Testing](#testing) -- [Localization](#localization) -- [Pull Request Process](#pull-request-process) -- [Branching Strategy](#branching-strategy) -- [Release Process](#release-process) -- [Security Considerations](#security-considerations) -- [Getting Help](#getting-help) - ## Prerequisites -- **Node.js** >= 22 (use `.nvmrc`: `nvm use`) -- **Yarn** v4.10.0 or newer -- **Chrome** or **Firefox** for testing the extension -- Familiarity with **TypeScript**, **React**, and browser extension architecture +| Tool | Version | Install | +| ----------------- | ------- | ------------------------------------------------------------ | +| Node.js | >= 22 | `nvm use` (reads `.nvmrc`) | +| Yarn | 4.10.0 | `corepack enable && corepack prepare yarn@4.10.0 --activate` | +| Chrome or Firefox | Latest | For loading and testing the extension | -## Repository Structure +## Getting Started -Freighter is a **Yarn workspaces monorepo** with four main areas: +### Quick Setup with an LLM -``` -freighter/ -├── extension/ # Browser extension (popup, background, content script) -├── @stellar/freighter-api/ # Client SDK published to npm — used by dApps -├── @shared/ # Shared utilities (api, constants, helpers) -│ ├── api/ -│ ├── constants/ -│ └── helpers/ -├── docs/ # Docusaurus site (docs.freighter.app) -├── config/ # Shared build configs (Jest, Babel, Webpack) -└── .github/ - ├── workflows/ # 10 CI/CD workflows - └── agents/ # Playwright test AI agents +If you use [Claude Code](https://claude.ai/code) or another LLM-powered coding +assistant, you can automate the setup. The repo includes a skill that checks +your environment, installs missing tools, configures `.env`, and verifies the +build. + +After cloning the repo, run: + +```bash +claude "/freighter-dev-setup" ``` -The extension itself has three runtime components: +The skill will: -| Component | Location | Purpose | -| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------- | -| **Popup** | `extension/src/popup` | React app — the UI users see when clicking the extension icon | -| **Background** | `extension/src/background` | Service worker — account creation, data storage, signing, responds to popup/content script messages | -| **Content Script** | `extension/src/contentScript` | Listens for `@stellar/freighter-api` messages via `window.postMessage`, relays them to the background | +1. Check all prerequisites (Node, Yarn, Chrome/Firefox) +2. Install what it can automatically (with your confirmation) +3. Produce a list of manual steps for anything it couldn't install +4. Set up `.env` with the public backend endpoints +5. Run verification to confirm the build works -## Development Setup +If you don't use Claude Code, follow the manual setup below. -### 1. Clone and install +### Manual Setup ```bash git clone https://github.com/stellar/freighter.git cd freighter -nvm use # Switches to Node 22 -yarn setup # Installs dependencies and allows scripts +nvm use # Switches to Node 22 +yarn setup # Installs dependencies and allows scripts ``` -### 2. Configure environment +### Environment Variables Create `extension/.env`: ```env INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 -INDEXER_V2_URL=https://freighter-backend-v2-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 ``` -### 3. Start development +These are the public production endpoints — the only required variables for +local development. To run your own backend, see +[stellar/wallet-backend](https://github.com/stellar/wallet-backend). -```bash -yarn start -``` - -This starts all workspaces in parallel: - -- `@stellar/freighter-api` — SDK build in watch mode -- `docs` — Docusaurus dev server on `localhost:3000` -- Extension dev server — popup on `localhost:9000` -- Extension build — outputs to `extension/build/` - -To start a single workspace: +### Run the Extension ```bash -yarn start:extension # Extension only -yarn start:freighter-api # SDK only -yarn start:docs # Docs only +yarn start # Starts all workspaces in parallel ``` -### 4. Load the extension in your browser - -**Chrome:** - -1. Navigate to `chrome://extensions` -2. Enable "Developer mode" -3. Click "Load unpacked" and select `extension/build/` - -**Firefox:** - -1. Navigate to `about:debugging#/runtime/this-firefox` -2. Click "Load Temporary Add-on" and select `extension/build/manifest.json` - -### 5. Hot reload caveats - -- **Popup changes** hot reload automatically via the dev server at - `localhost:9000` -- **Background/content script changes** require running `yarn build:extension` - and reloading the extension in the browser - -## Development Workflow - -### Common commands - -| Command | Purpose | -| ----------------------------------- | ---------------------------------- | -| `yarn start` | Start all workspaces (dev mode) | -| `yarn build` | Build all workspaces | -| `yarn build:extension` | Dev build of extension | -| `yarn build:extension:experimental` | Build with experimental features | -| `yarn build:extension:production` | Minified production build | -| `yarn test` | Run unit tests (watch mode) | -| `yarn test:ci` | Run unit tests (CI mode, no watch) | -| `yarn test:e2e` | Run Playwright e2e tests | - -### Dev server URLs - -| URL | Purpose | -| ----------------------------------- | ----------------------------------------- | -| `localhost:9000` | Extension popup (dev) | -| `localhost:9000/#/debug` | Blockaid debug panel | -| `localhost:9000/#/integration-test` | Integration test helper (clears app data) | -| `localhost:3000` | Documentation site | - -### Build variants - -- **Standard** (`yarn build:extension`) — for everyday development -- **Experimental** (`yarn build:extension:experimental`) — enables - feature-flagged features -- **Production** (`yarn build:extension:production`) — minified, security - guardrails enabled, cannot connect to dev server - -## Code Style & Conventions - -### Formatting & linting - -Code style is enforced automatically via pre-commit hooks. You rarely need to -run these manually: +This runs the extension dev server (`localhost:9000`), SDK build in watch mode, +and Docusaurus (`localhost:3000`). -- **Prettier** formats code on commit (config: `.prettierrc.yaml`) -- **ESLint** fixes lint issues on commit (config: `eslint.config.js`) +To start a single workspace: `yarn start:extension`, `yarn start:freighter-api`, +or `yarn start:docs`. -Key formatting rules: +**Load in Chrome:** -- Double quotes (`"`) -- 2-space indentation, no tabs -- Trailing commas everywhere -- 80-character line width -- Semicolons required +1. Go to `chrome://extensions`, enable "Developer mode" +2. Click "Load unpacked", select `extension/build/` -### Pre-commit hooks +**Load in Firefox:** -On every commit, Husky runs: +1. Go to `about:debugging#/runtime/this-firefox` +2. Click "Load Temporary Add-on", select `extension/build/manifest.json` -1. `pretty-quick --staged` — formats staged files -2. `lint-staged` — runs ESLint `--fix` on staged `.ts`/`.tsx` files -3. Translation build — auto-generates `extension/src/popup/locales/` files +### Hot Reload -If using nvm, create `~/.huskyrc` to ensure the correct Node version loads for -hooks. +- **Popup changes** hot reload via the dev server at `localhost:9000` +- **Background/content script changes** require `yarn build:extension` + reload + the extension in the browser -### Navigation +### Dev URLs -Use `navigateTo` from `popup/helpers/navigate` for all navigation. Use the -`ROUTES` enum from `popup/constants/routes` instead of hardcoded path strings. -See `extension/STYLEGUIDE.MD` for details. +| URL | Purpose | +| ----------------------------------- | ----------------------- | +| `localhost:9000` | Extension popup | +| `localhost:9000/#/debug` | Blockaid debug panel | +| `localhost:9000/#/integration-test` | Integration test helper | +| `localhost:3000` | Documentation site | -### Imports - -Organize imports with external packages first, then internal modules. ESLint -enforces this ordering. - -## Testing - -### Unit tests (Jest) - -```bash -yarn test # Watch mode -yarn test:ci # CI mode (no watch) -``` - -- Tests live in `__tests__/` directories alongside source files -- Environment: JSDOM (`jest-fixed-jsdom`) -- Coverage collected from `src/**/*.{ts,tsx,mjs}` - -### E2E tests (Playwright) +## Key Commands ```bash -yarn test:e2e # Run all tests -yarn test:e2e sendPayment.test.ts # Specific test file -yarn test:e2e --ui # Interactive UI mode -yarn test:e2e --headed # See the browser -yarn test:e2e -g "Send doesn't throw" # Run by test name -PWDEBUG=1 npx playwright test # Debug mode +yarn build:extension # Dev build +yarn build:extension:experimental # Experimental features enabled +yarn build:extension:production # Minified production build +yarn test # Jest unit tests (watch mode) +yarn test:ci # Jest CI mode (no watch) +yarn test:e2e # Playwright e2e tests ``` -**Configuration:** - -- Browser: Chromium only -- Viewport: 1280x720 -- Timeout: 15 seconds per test, 5 retries -- Workers: 8 locally, 4 on CI - -**Snapshot testing:** - -- Visual snapshots stored in `[testName].test.ts-snapshots/` -- Update baselines: `yarn test:e2e --update-snapshots` - -For the full e2e testing guide, see -[`extension/e2e-tests/README.md`](extension/e2e-tests/README.md). - -### Before submitting a PR +See `package.json` for the complete list of scripts. -- All unit tests must pass (`yarn test:ci`) -- Run relevant e2e tests for your change area -- CI runs both Jest and Playwright on every PR +## Code Conventions -## Localization +- **Formatting:** Double quotes, 2-space indent, trailing commas, 80-char width, + semicolons. Enforced by Prettier (`.prettierrc.yaml`). +- **Linting:** ESLint with auto-fix. Config in `eslint.config.js`. +- **Navigation:** Use `navigateTo` helper + `ROUTES` enum — never hardcoded + paths. See [`extension/STYLEGUIDE.MD`](extension/STYLEGUIDE.MD). +- **Imports:** External packages first, then internal. ESLint enforces ordering. +- **Translations:** All user-facing strings through `t()` from `react-i18next`. + See [`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD). -Freighter uses `react-i18next` for translations. See -[`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD) for the full guide. +### Pre-commit Hooks -**Quick summary:** +Husky runs on every commit: -1. Wrap user-facing strings with the `t()` function from the `useTranslation` - hook -2. Add the key/value pair to all language JSON files in - `extension/src/popup/locales/` -3. Run `yarn build:extension:translations` to auto-generate missing keys - (defaults to English) +1. `pretty-quick --staged` — Prettier on staged files +2. `lint-staged` — ESLint fix on staged `.ts`/`.tsx` +3. Translation build — auto-generates locale files -Translation files are auto-built and staged on every commit via the pre-commit -hook. +If using nvm, create `~/.huskyrc` to ensure the correct Node version loads. -**Testing translations:** Change your browser language, clear the -`react-i18next` localStorage value, and refresh. +## Architecture -## Pull Request Process +The extension has three runtime contexts communicating via message passing: -### Branch naming +| Context | Location | Purpose | +| ------------------ | ------------------------------ | ----------------------------------------------------------- | +| **Popup** | `extension/src/popup/` | React app — UI the user sees | +| **Background** | `extension/src/background/` | Service worker — keys, signing, storage, message handling | +| **Content Script** | `extension/src/contentScript/` | Bridges `window.postMessage` from dApps to `chrome.runtime` | -Use prefixed branch names: - -| Prefix | Use | -| ---------- | --------------------------------- | -| `feature/` | New features | -| `fix/` | Bug fixes | -| `chore/` | Maintenance, refactoring, tooling | -| `bugfix/` | Alternative bug fix prefix | - -### Commit messages - -Start with an action verb in present tense. Keep the subject concise. +**Monorepo structure:** ``` -Add hardware wallet support for Trezor -Fix transaction signing for multi-sig accounts -Update Soroswap SDK to v2.0 -Improve asset list loading performance +freighter/ +├── extension/ # Browser extension (popup, background, content script) +├── @stellar/freighter-api/ # npm SDK for dApp integration +├── @shared/ # Shared code (api, constants, helpers) +├── docs/ # Docusaurus site (docs.freighter.app) +└── config/ # Shared build configs ``` -### PR expectations - -- **Keep PRs focused** — don't mix refactoring with feature changes -- **Include screenshots or videos** for UI changes (before/after) -- **Self-review** your code before requesting review -- **Add tests** for new functionality -- **Test on both Chrome and Firefox** when touching extension behavior -- **Update translations** if adding user-facing strings (the pre-commit hook - handles generation) - -### CI checks - -Every PR triggers: - -- **Jest unit tests** + **Playwright e2e tests** (`runTests.yml`) -- **CodeQL** security analysis (`codeql.yml`) - -Your PR must pass all checks before merging. +## Testing -## Branching Strategy +**Unit tests:** Jest with JSDOM. Tests in `__tests__/` alongside source. Run +`yarn test` (watch) or `yarn test:ci`. -| Branch | Purpose | -| ------------------- | ----------------------------------------------------------- | -| `master` | Main development branch | -| `release` | Release candidate branch (auto-created by release workflow) | -| `emergency-release` | Hotfix branch for emergency patches | -| `v{X.Y.Z}` | Version branches created during release (e.g., `v5.39.0`) | +**E2E tests:** Playwright with Chromium. See +[`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) for setup and +writing tests. -All feature/fix branches are created from and merged back into `master`. +```bash +yarn test:e2e # All tests +yarn test:e2e sendPayment.test.ts # Specific file +yarn test:e2e --ui # Interactive mode +``` -## Release Process +**Before submitting a PR:** `yarn test:ci` must pass. Test on both Chrome and +Firefox when touching extension behavior. -Releases are orchestrated via the `newRelease.yml` GitHub Actions workflow: +## Pull Requests -1. **Trigger:** Manual dispatch with `appVersion` (e.g., `5.39.0`) and source - branch -2. **Automation:** Creates `release` and `v{VERSION}` branches, bumps versions - in `package.json` and `manifest.json`, generates release notes, creates a PR -3. **Submission workflows:** Separate workflows handle Chrome Web Store, Firefox - AMO, Safari, and npm publishing +- Branch from `master` with a type prefix: `feature/`, `fix/`, `chore/`, + `refactor/`, `bugfix/` +- Commit messages: start with action verb (`Add`, `Fix`, `Update`, `Improve`) +- No mixed concerns — keep refactoring separate from features +- Include before/after screenshots for UI changes +- Update translations if adding user-facing strings (pre-commit hook handles + generation) +- Test on both Chrome and Firefox -You generally don't need to worry about the release process unless you're a -maintainer. +**CI runs on every PR:** Jest + Playwright (`runTests.yml`), CodeQL security +analysis (`codeql.yml`). All must pass. -## Security Considerations +## Security -Freighter handles private keys and signs transactions. When contributing, keep -these principles in mind: +Freighter handles private keys and signs transactions. When contributing: -- **Never log or expose private keys**, seed phrases, or passwords — not even in - debug builds -- **Validate all data** coming from external sources (dApp messages via content - script, API responses) -- **Do not bypass** Content Security Policy (CSP) or weaken existing security - guardrails +- **Never log or expose** private keys, seed phrases, or passwords +- **Validate all external data** — dApp messages via content script, API + responses +- **Don't bypass CSP** or weaken existing security guardrails - **Be careful with `window.postMessage`** — the content script is an attack - surface between dApps and the extension -- **Use production builds** (`yarn build:extension:production`) when testing - security-sensitive flows — production builds have additional guardrails + surface +- **Use production builds** for testing security-sensitive flows (extra + guardrails) - **Report vulnerabilities** via the [Stellar Security Policy](https://github.com/stellar/.github/blob/master/SECURITY.md) - — do not open public issues for security bugs - -## Getting Help - -- **Extension architecture:** See [`extension/README.md`](extension/README.md) - for the popup/background/content script model -- **Hardware wallet integration:** See - [`extension/INTEGRATING_HARDWARE_WALLET.MD`](extension/INTEGRATING_HARDWARE_WALLET.MD) -- **Soroswap integration:** See - [`extension/INTEGRATING_SOROSWAP.MD`](extension/INTEGRATING_SOROSWAP.MD) -- **API reference:** See interactive playgrounds at - [docs.freighter.app](https://docs.freighter.app) -- **E2E testing:** See - [`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) -- **Questions:** Open a - [GitHub Discussion](https://github.com/stellar/freighter/discussions) or reach - out on the [Stellar Developer Discord](https://discord.gg/stellardev) + — not public issues + +## Further Reading + +| Topic | Location | +| --------------------------- | -------------------------------------------------------------------------------------- | +| Extension dev guide | [`extension/README.md`](extension/README.md) | +| Hardware wallet integration | [`extension/INTEGRATING_HARDWARE_WALLET.MD`](extension/INTEGRATING_HARDWARE_WALLET.MD) | +| Soroswap integration | [`extension/INTEGRATING_SOROSWAP.MD`](extension/INTEGRATING_SOROSWAP.MD) | +| Localization guide | [`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD) | +| Style guide | [`extension/STYLEGUIDE.MD`](extension/STYLEGUIDE.MD) | +| E2E testing | [`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) | +| API playgrounds | [docs.freighter.app](https://docs.freighter.app) | +| All scripts & commands | `package.json` | + +**Questions?** Open a +[GitHub Discussion](https://github.com/stellar/freighter/discussions) or join +the [Stellar Developer Discord](https://discord.gg/stellardev). diff --git a/README.md b/README.md index 82313be3d4..2fd4013ffb 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,12 @@ This repo is constructed using yarn workspaces and consists of the 4 sections: ## Prerequisites -You will need +- Node (>= 22): https://nodejs.org/en/download/ (use `nvm use` — the repo has + `.nvmrc`) +- Yarn 4.10.0: `corepack enable && corepack prepare yarn@4.10.0 --activate` -- Node (>=21): https://nodejs.org/en/download/ -- Yarn (v1.22.5 or newer): https://classic.yarnpkg.com/en/docs/install +For a complete setup guide including LLM-assisted setup, see +[CONTRIBUTING.md](CONTRIBUTING.md). ## Build the extension @@ -46,7 +48,7 @@ file `extension/.env` with the following variables: ``` INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 -INDEXER_V2_URL=https://freighter-backend-v2-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 ``` These URLs point to the production Freighter backend. For more details on From 1c62fc8b63efb86ce272bae6d3dfca6d25c4bf56 Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 12:09:58 -0300 Subject: [PATCH 03/10] update contributing guide --- .claude/skills/freighter-dev-setup/SKILL.md | 32 ++++++++++++++------- README.md | 2 +- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/.claude/skills/freighter-dev-setup/SKILL.md b/.claude/skills/freighter-dev-setup/SKILL.md index 551d966e57..2f2cebb0e2 100644 --- a/.claude/skills/freighter-dev-setup/SKILL.md +++ b/.claude/skills/freighter-dev-setup/SKILL.md @@ -26,7 +26,7 @@ restrictions), fall back to `which ` to confirm presence. node --version 2>&1 || which node # nvm (needed for node version management — repo has .nvmrc) -command -v nvm 2>&1 || test -d "$HOME/.nvm" && echo "nvm found" +if command -v nvm >/dev/null 2>&1 || test -d "$HOME/.nvm"; then echo "nvm found"; else echo "nvm missing"; fi # Corepack corepack --version 2>&1 || which corepack @@ -35,8 +35,16 @@ corepack --version 2>&1 || which corepack yarn --version 2>&1 || which yarn # Browser (at least one needed for testing the extension) -test -d "/Applications/Google Chrome.app" && echo "Chrome: found" || echo "Chrome: not found" -test -d "/Applications/Firefox.app" && echo "Firefox: found" || echo "Firefox: not found" +# macOS +if [ "$(uname -s)" = "Darwin" ]; then + test -d "/Applications/Google Chrome.app" && echo "Chrome: found" || echo "Chrome: not found" + test -d "/Applications/Firefox.app" && echo "Firefox: found" || echo "Firefox: not found" +else + # Linux/other + command -v google-chrome >/dev/null 2>&1 || command -v google-chrome-stable >/dev/null 2>&1 || command -v chromium >/dev/null 2>&1 || command -v chromium-browser >/dev/null 2>&1 + test $? -eq 0 && echo "Chrome: found" || echo "Chrome: not found" + command -v firefox >/dev/null 2>&1 && echo "Firefox: found" || echo "Firefox: not found" +fi # Playwright (for e2e tests — installed via yarn, just check availability) npx playwright --version 2>&1 || echo "Playwright: will be installed via yarn" @@ -72,13 +80,17 @@ summary. **Auto-installable (run after user confirms):** -| Missing tool | Install command | -| --------------- | ------------------------------------------------------------------------------------------------- | -| Homebrew | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` | -| nvm | `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh \| bash` | -| Node.js 22 | `nvm install 22` | -| Corepack + Yarn | `corepack enable && corepack prepare yarn@4.10.0 --activate` | -| Chrome | `brew install --cask google-chrome` | +- **Homebrew** (macOS): + `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` +- **nvm**: + `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash` + — then source nvm: + `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"` +- **Node.js 22**: `nvm install 22` +- **Corepack + Yarn**: + `corepack enable && corepack prepare yarn@4.10.0 --activate` +- **Chrome**: `brew install --cask google-chrome` (macOS) or install via system + package manager (Linux) **Manual — guide the user:** diff --git a/README.md b/README.md index 2fd4013ffb..3101fcd9d9 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ This repo is constructed using yarn workspaces and consists of the 4 sections: - Yarn 4.10.0: `corepack enable && corepack prepare yarn@4.10.0 --activate` For a complete setup guide including LLM-assisted setup, see -[CONTRIBUTING.md](CONTRIBUTING.md). +[CONTRIBUTING.MD](CONTRIBUTING.MD). ## Build the extension From e625f56ee2d4c9f98a67a4b82d4ce2f1e30b29eb Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 12:12:32 -0300 Subject: [PATCH 04/10] update mention of claude to llm agnostic --- CONTRIBUTING.MD | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index cf42798720..0c40e94d62 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -18,12 +18,12 @@ For the Stellar organization's general contribution guidelines, see the ### Quick Setup with an LLM -If you use [Claude Code](https://claude.ai/code) or another LLM-powered coding -assistant, you can automate the setup. The repo includes a skill that checks -your environment, installs missing tools, configures `.env`, and verifies the -build. +If you use an LLM-powered coding assistant, you can automate the setup. The repo +includes a setup skill (`.claude/skills/freighter-dev-setup/SKILL.md`) that +checks your environment, installs missing tools, configures `.env`, and verifies +the build. -After cloning the repo, run: +Point your LLM assistant at the skill file, or if using Claude Code: ```bash claude "/freighter-dev-setup" @@ -37,7 +37,7 @@ The skill will: 4. Set up `.env` with the public backend endpoints 5. Run verification to confirm the build works -If you don't use Claude Code, follow the manual setup below. +If you don't use an LLM assistant, follow the manual setup below. ### Manual Setup From 169d7d895c23f883cf4cc37bb22741c9719bc2b4 Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 12:15:46 -0300 Subject: [PATCH 05/10] update mention of claude to llm agnostic --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3101fcd9d9..7fb40b7ec9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ This repo is constructed using yarn workspaces and consists of the 4 sections: `.nvmrc`) - Yarn 4.10.0: `corepack enable && corepack prepare yarn@4.10.0 --activate` -For a complete setup guide including LLM-assisted setup, see +For a complete setup guide including LLM-assisted quick setup, see [CONTRIBUTING.MD](CONTRIBUTING.MD). ## Build the extension From 4f3138060c0dc6556d7d33883b622c756ca24d3e Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 14:06:17 -0300 Subject: [PATCH 06/10] Add contributing guide with LLM quick start instructions Co-Authored-By: Claude Opus 4.6 (1M context) --- CONTRIBUTING.MD | 54 +++++++++++++--- LLM-QUICK-START.md | 150 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 7 deletions(-) create mode 100644 LLM-QUICK-START.md diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 0c40e94d62..8adf4e316f 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -19,15 +19,11 @@ For the Stellar organization's general contribution guidelines, see the ### Quick Setup with an LLM If you use an LLM-powered coding assistant, you can automate the setup. The repo -includes a setup skill (`.claude/skills/freighter-dev-setup/SKILL.md`) that +includes a quick start guide ([`LLM-QUICK-START.md`](LLM-QUICK-START.md)) that checks your environment, installs missing tools, configures `.env`, and verifies the build. -Point your LLM assistant at the skill file, or if using Claude Code: - -```bash -claude "/freighter-dev-setup" -``` +Point your LLM assistant at `LLM-QUICK-START.md` and ask it to follow the steps. The skill will: @@ -59,7 +55,10 @@ INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 These are the public production endpoints — the only required variables for local development. To run your own backend, see -[stellar/wallet-backend](https://github.com/stellar/wallet-backend). +[stellar/freighter-backend](https://github.com/stellar/freighter-backend) (V1) +and +[stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2) +(V2). ### Run the Extension @@ -171,6 +170,47 @@ yarn test:e2e --ui # Interactive mode **Before submitting a PR:** `yarn test:ci` must pass. Test on both Chrome and Firefox when touching extension behavior. +## Adding Features + +### Adding a new feature end-to-end + +A typical extension feature touches all three runtime contexts: + +1. **Popup** — add the UI in `extension/src/popup/` (React component + route) +2. **Background** — add the handler in `extension/src/background/` (message + listener, storage, or signing logic) +3. **Content Script** — if the feature involves dApp communication, add the + message relay in `extension/src/contentScript/` + +Use typed message enums for popup <-> background <-> content script +communication. Follow existing patterns in the codebase. + +### Adding a new API method to `@stellar/freighter-api` + +1. Add the method in `@stellar/freighter-api/src/` +2. Add the corresponding message handler in `extension/src/background/` +3. Add the content script relay in `extension/src/contentScript/` +4. Add an interactive playground in `docs/docs/playground/` +5. Update the API docs at `docs.freighter.app` + +### Running the backend locally + +The extension connects to two separate backend services: + +- **V1** `INDEXER_URL` → + [stellar/freighter-backend](https://github.com/stellar/freighter-backend) + (TypeScript) — balances, subscriptions, feature flags, notifications +- **V2** `INDEXER_V2_URL` → + [stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2) + (Go) — collectibles, RPC health, ledger keys, protocols + +To run your own: + +1. Clone the repo for the backend you need (V1, V2, or both) +2. Follow its README for setup +3. Update `INDEXER_URL` and/or `INDEXER_V2_URL` in `extension/.env` to point at + your local instance + ## Pull Requests - Branch from `master` with a type prefix: `feature/`, `fix/`, `chore/`, diff --git a/LLM-QUICK-START.md b/LLM-QUICK-START.md new file mode 100644 index 0000000000..f2aa65e1b1 --- /dev/null +++ b/LLM-QUICK-START.md @@ -0,0 +1,150 @@ +# Freighter Extension — LLM Quick Start + +Evaluate the contributor's machine against all prerequisites for Freighter +(browser extension), install what's missing, and run the initial setup. + +## Step 1: Check all prerequisites + +Run every check below and collect results. Report all at once — don't stop at +the first failure. + +For each tool, try the version command first. If it fails (e.g., sandbox +restrictions), fall back to `which ` to confirm presence. + +```bash +# Node.js >= 22 +node --version 2>&1 || which node + +# nvm (needed for node version management — repo has .nvmrc) +if command -v nvm >/dev/null 2>&1 || test -d "$HOME/.nvm"; then echo "nvm found"; else echo "nvm missing"; fi + +# Corepack +corepack --version 2>&1 || which corepack + +# Yarn 4.10.0 +yarn --version 2>&1 || which yarn + +# Browser (at least one needed for testing the extension) +# macOS +if [ "$(uname -s)" = "Darwin" ]; then + test -d "/Applications/Google Chrome.app" && echo "Chrome: found" || echo "Chrome: not found" + test -d "/Applications/Firefox.app" && echo "Firefox: found" || echo "Firefox: not found" +else + # Linux/other + command -v google-chrome >/dev/null 2>&1 || command -v google-chrome-stable >/dev/null 2>&1 || command -v chromium >/dev/null 2>&1 || command -v chromium-browser >/dev/null 2>&1 + test $? -eq 0 && echo "Chrome: found" || echo "Chrome: not found" + command -v firefox >/dev/null 2>&1 && echo "Firefox: found" || echo "Firefox: not found" +fi + +# Playwright (for e2e tests — installed via yarn, just check availability) +npx playwright --version 2>&1 || echo "Playwright: will be installed via yarn" +``` + +## Step 2: Present results + +Show a clear summary: + +``` +Freighter Extension — Prerequisites Check +========================================== + Node.js v22.x.x >= 22 required OK + nvm found any OK + Corepack 0.x.x any OK + Yarn 4.10.0 4.10.0 required OK + Chrome found at least one browser OK + Firefox not found (Chrome is enough) OK + Playwright via yarn for e2e tests OK +``` + +## Step 3: Install missing tools + +Present the missing tools and ask the user: "I can install [list] automatically. +Want me to proceed?" + +If the user confirms, **run the install commands** for each missing tool. After +each install, re-check the version to confirm it succeeded. If an install fails, +report the error and continue with the next tool. + +If the user declines, skip to Step 4 and note the missing tools in the final +summary. + +**Auto-installable (run after user confirms):** + +- **Homebrew** (macOS): + `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` +- **nvm**: + `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash` + — then source nvm: + `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"` +- **Node.js 22**: `nvm install 22` +- **Corepack + Yarn**: + `corepack enable && corepack prepare yarn@4.10.0 --activate` +- **Chrome**: `brew install --cask google-chrome` (macOS) or install via system + package manager (Linux) + +**Manual — guide the user:** + +- If using nvm, create `~/.huskyrc` so pre-commit hooks load the correct Node + version: + ```bash + export NVM_DIR="$HOME/.nvm" + [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" + ``` + +## Step 4: Run initial setup + +```bash +nvm use # Switch to Node 22 (.nvmrc) +yarn setup # Install deps + allow scripts +``` + +## Step 5: Configure environment + +Check if `extension/.env` exists. If not, create it with the required variables: + +```env +INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 +INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 +``` + +These are the public production endpoints — the only required variables for +local development. To run your own backend, see +[stellar/freighter-backend](https://github.com/stellar/freighter-backend) (V1) +and +[stellar/freighter-backend-v2](https://github.com/stellar/freighter-backend-v2) +(V2). + +If `extension/.env` already exists, verify it has both `INDEXER_URL` and +`INDEXER_V2_URL` set. + +## Step 6: Verify + +```bash +yarn build:extension +``` + +If the build succeeds, tell the user they're ready: + +1. Run `yarn start` +2. Open `chrome://extensions` (or `about:debugging` in Firefox) +3. Load unpacked from `extension/build/` +4. The popup is at `localhost:9000` + +If the build fails, read the error and diagnose — common causes are missing +`.env` vars or wrong Node version. + +## Step 7: Summary + +At the end, produce a final summary: + +``` +Setup Complete +============== + Installed: [list of tools installed] + Configured: extension/.env with backend endpoints + + Ready to run: + 1. yarn start + 2. Load extension/build/ in Chrome (chrome://extensions > Load unpacked) + 3. Popup at localhost:9000 +``` From fc557adb5996ec55979ab8ef1e917250e5585045 Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 14:30:22 -0300 Subject: [PATCH 07/10] Remove skill file moved to LLM-QUICK-START.md Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/freighter-dev-setup/SKILL.md | 157 -------------------- 1 file changed, 157 deletions(-) delete mode 100644 .claude/skills/freighter-dev-setup/SKILL.md diff --git a/.claude/skills/freighter-dev-setup/SKILL.md b/.claude/skills/freighter-dev-setup/SKILL.md deleted file mode 100644 index 2f2cebb0e2..0000000000 --- a/.claude/skills/freighter-dev-setup/SKILL.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -name: freighter-dev-setup -description: - Check, install, and configure all prerequisites for Freighter extension - development. Use when a contributor says "set up my dev environment", "quick - setup", "check my setup", "what do I need to install", or encounters build - failures from missing dependencies. Also use when someone clones the repo for - the first time. ---- - -# Freighter Extension Dev Setup - -Evaluate the contributor's machine against all prerequisites for Freighter -(browser extension), install what's missing, and run the initial setup. - -## Step 1: Check all prerequisites - -Run every check below and collect results. Report all at once — don't stop at -the first failure. - -For each tool, try the version command first. If it fails (e.g., sandbox -restrictions), fall back to `which ` to confirm presence. - -```bash -# Node.js >= 22 -node --version 2>&1 || which node - -# nvm (needed for node version management — repo has .nvmrc) -if command -v nvm >/dev/null 2>&1 || test -d "$HOME/.nvm"; then echo "nvm found"; else echo "nvm missing"; fi - -# Corepack -corepack --version 2>&1 || which corepack - -# Yarn 4.10.0 -yarn --version 2>&1 || which yarn - -# Browser (at least one needed for testing the extension) -# macOS -if [ "$(uname -s)" = "Darwin" ]; then - test -d "/Applications/Google Chrome.app" && echo "Chrome: found" || echo "Chrome: not found" - test -d "/Applications/Firefox.app" && echo "Firefox: found" || echo "Firefox: not found" -else - # Linux/other - command -v google-chrome >/dev/null 2>&1 || command -v google-chrome-stable >/dev/null 2>&1 || command -v chromium >/dev/null 2>&1 || command -v chromium-browser >/dev/null 2>&1 - test $? -eq 0 && echo "Chrome: found" || echo "Chrome: not found" - command -v firefox >/dev/null 2>&1 && echo "Firefox: found" || echo "Firefox: not found" -fi - -# Playwright (for e2e tests — installed via yarn, just check availability) -npx playwright --version 2>&1 || echo "Playwright: will be installed via yarn" -``` - -## Step 2: Present results - -Show a clear summary: - -``` -Freighter Extension — Prerequisites Check -========================================== - Node.js v22.x.x >= 22 required OK - nvm found any OK - Corepack 0.x.x any OK - Yarn 4.10.0 4.10.0 required OK - Chrome found at least one browser OK - Firefox not found (Chrome is enough) OK - Playwright via yarn for e2e tests OK -``` - -## Step 3: Install missing tools - -Present the missing tools and ask the user: "I can install [list] automatically. -Want me to proceed?" - -If the user confirms, **run the install commands** for each missing tool. After -each install, re-check the version to confirm it succeeded. If an install fails, -report the error and continue with the next tool. - -If the user declines, skip to Step 4 and note the missing tools in the final -summary. - -**Auto-installable (run after user confirms):** - -- **Homebrew** (macOS): - `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` -- **nvm**: - `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash` - — then source nvm: - `export NVM_DIR="$HOME/.nvm" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"` -- **Node.js 22**: `nvm install 22` -- **Corepack + Yarn**: - `corepack enable && corepack prepare yarn@4.10.0 --activate` -- **Chrome**: `brew install --cask google-chrome` (macOS) or install via system - package manager (Linux) - -**Manual — guide the user:** - -- If using nvm, create `~/.huskyrc` so pre-commit hooks load the correct Node - version: - ```bash - export NVM_DIR="$HOME/.nvm" - [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" - ``` - -## Step 4: Run initial setup - -```bash -nvm use # Switch to Node 22 (.nvmrc) -yarn setup # Install deps + allow scripts -``` - -## Step 5: Configure environment - -Check if `extension/.env` exists. If not, create it with the required variables: - -```env -INDEXER_URL=https://freighter-backend-prd.stellar.org/api/v1 -INDEXER_V2_URL=https://freighter-backend-v2.stellar.org/api/v1 -``` - -These are the public production endpoints — the only required variables for -local development. To run your own backend, see -[stellar/wallet-backend](https://github.com/stellar/wallet-backend). - -If `extension/.env` already exists, verify it has both `INDEXER_URL` and -`INDEXER_V2_URL` set. - -## Step 6: Verify - -```bash -yarn build:extension -``` - -If the build succeeds, tell the user they're ready: - -1. Run `yarn start` -2. Open `chrome://extensions` (or `about:debugging` in Firefox) -3. Load unpacked from `extension/build/` -4. The popup is at `localhost:9000` - -If the build fails, read the error and diagnose — common causes are missing -`.env` vars or wrong Node version. - -## Step 7: Summary - -At the end, produce a final summary: - -``` -Setup Complete -============== - Installed: [list of tools installed] - Configured: extension/.env with backend endpoints - - Ready to run: - 1. yarn start - 2. Load extension/build/ in Chrome (chrome://extensions > Load unpacked) - 3. Popup at localhost:9000 -``` From b38b51ed925856000ee5d3ea1c1e355957b740db Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 14:51:40 -0300 Subject: [PATCH 08/10] Update contributing.md file information --- CONTRIBUTING.MD | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 8adf4e316f..76312b5be0 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -25,6 +25,9 @@ the build. Point your LLM assistant at `LLM-QUICK-START.md` and ask it to follow the steps. +For detailed best practices and coding guidelines when working with an LLM, see +[`docs/skills/freighter-best-practices`](docs/skills/freighter-best-practices/). + The skill will: 1. Check all prerequisites (Node, Yarn, Chrome/Firefox) @@ -253,6 +256,7 @@ Freighter handles private keys and signs transactions. When contributing: | E2E testing | [`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) | | API playgrounds | [docs.freighter.app](https://docs.freighter.app) | | All scripts & commands | `package.json` | +| Best practices (LLM guide) | [`docs/skills/freighter-best-practices`](docs/skills/freighter-best-practices/) | **Questions?** Open a [GitHub Discussion](https://github.com/stellar/freighter/discussions) or join From 2083543ec2a618c319f3189c3d035f44aac36c4b Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Wed, 8 Apr 2026 16:01:53 -0300 Subject: [PATCH 09/10] fix adjustments from copilot review --- CONTRIBUTING.MD | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 76312b5be0..0a189931b2 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -26,7 +26,8 @@ the build. Point your LLM assistant at `LLM-QUICK-START.md` and ask it to follow the steps. For detailed best practices and coding guidelines when working with an LLM, see -[`docs/skills/freighter-best-practices`](docs/skills/freighter-best-practices/). +the `freighter-best-practices` guide (located in +`docs/skills/freighter-best-practices/` once available). The skill will: @@ -120,7 +121,7 @@ See `package.json` for the complete list of scripts. - **Linting:** ESLint with auto-fix. Config in `eslint.config.js`. - **Navigation:** Use `navigateTo` helper + `ROUTES` enum — never hardcoded paths. See [`extension/STYLEGUIDE.MD`](extension/STYLEGUIDE.MD). -- **Imports:** External packages first, then internal. ESLint enforces ordering. +- **Imports:** Keep external packages first, then internal. - **Translations:** All user-facing strings through `t()` from `react-i18next`. See [`extension/LOCALIZATION.MD`](extension/LOCALIZATION.MD). @@ -128,9 +129,8 @@ See `package.json` for the complete list of scripts. Husky runs on every commit: -1. `pretty-quick --staged` — Prettier on staged files -2. `lint-staged` — ESLint fix on staged `.ts`/`.tsx` -3. Translation build — auto-generates locale files +1. `./.husky/addTranslations.sh` — auto-generates locale files +2. `pretty-quick --staged` — runs Prettier on staged files If using nvm, create `~/.huskyrc` to ensure the correct Node version loads. @@ -256,7 +256,7 @@ Freighter handles private keys and signs transactions. When contributing: | E2E testing | [`extension/e2e-tests/README.md`](extension/e2e-tests/README.md) | | API playgrounds | [docs.freighter.app](https://docs.freighter.app) | | All scripts & commands | `package.json` | -| Best practices (LLM guide) | [`docs/skills/freighter-best-practices`](docs/skills/freighter-best-practices/) | +| Best practices (LLM guide) | `docs/skills/freighter-best-practices/` (once available) | **Questions?** Open a [GitHub Discussion](https://github.com/stellar/freighter/discussions) or join From f1abe4c49df00d3d56dce08df900599be67057f1 Mon Sep 17 00:00:00 2001 From: leofelix077 Date: Thu, 9 Apr 2026 15:05:15 -0300 Subject: [PATCH 10/10] Rename LLM-QUICK-START.md to quick-start-guide.md Use a more human-readable filename and update references in CONTRIBUTING.MD. --- CONTRIBUTING.MD | 9 +++++---- LLM-QUICK-START.md => quick-start-guide.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) rename LLM-QUICK-START.md => quick-start-guide.md (99%) diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD index 0a189931b2..6ccccf9755 100644 --- a/CONTRIBUTING.MD +++ b/CONTRIBUTING.MD @@ -19,11 +19,12 @@ For the Stellar organization's general contribution guidelines, see the ### Quick Setup with an LLM If you use an LLM-powered coding assistant, you can automate the setup. The repo -includes a quick start guide ([`LLM-QUICK-START.md`](LLM-QUICK-START.md)) that -checks your environment, installs missing tools, configures `.env`, and verifies -the build. +includes a quick start guide ([`quick-start-guide.md`](quick-start-guide.md)) +that checks your environment, installs missing tools, configures `.env`, and +verifies the build. -Point your LLM assistant at `LLM-QUICK-START.md` and ask it to follow the steps. +Point your LLM assistant at `quick-start-guide.md` and ask it to follow the +steps. For detailed best practices and coding guidelines when working with an LLM, see the `freighter-best-practices` guide (located in diff --git a/LLM-QUICK-START.md b/quick-start-guide.md similarity index 99% rename from LLM-QUICK-START.md rename to quick-start-guide.md index f2aa65e1b1..58900dd600 100644 --- a/LLM-QUICK-START.md +++ b/quick-start-guide.md @@ -1,4 +1,4 @@ -# Freighter Extension — LLM Quick Start +# Freighter Extension — Quick Start Guide Evaluate the contributor's machine against all prerequisites for Freighter (browser extension), install what's missing, and run the initial setup.