freighter-best-practices

name

freighter-best-practices

description

Comprehensive best practices for the Freighter browser extension. Covers code style, architecture, security, testing, performance, error handling, i18n, messaging, git workflow, dependencies, and anti-patterns. Use when writing new features, reviewing PRs, adding message handlers, working with Redux, modifying content scripts, handling keys, building transactions, or any development work in the freighter extension repo. Triggers on any task touching the freighter codebase.

Freighter Best Practices

Freighter is a non-custodial Stellar wallet shipped as a browser extension (Manifest V3) for Chrome and Firefox. The repository is a Yarn workspaces monorepo with four main workspaces:

1. extension/ -- the browser extension itself (popup, background service worker, content scripts)
2. @stellar/freighter-api/ -- the npm SDK that dApps use to interact with Freighter
3. @shared/ -- shared packages (api, constants, helpers) consumed by multiple workspaces
4. docs/ -- documentation and skills

Reference Guide

Concern	File	When to Read
Code Style	references/code-style.md	Writing or reviewing any code
Architecture	references/architecture.md	Adding features, understanding the codebase
Security	references/security.md	Touching keys, messages, storage, or dApp interactions
Testing	references/testing.md	Writing or fixing tests
Performance	references/performance.md	Optimizing renders, bundle size, or load times
Error Handling	references/error-handling.md	Adding error states, catch blocks, or user-facing errors
Internationalization	references/i18n.md	Adding or modifying user-facing strings
Messaging	references/messaging.md	Adding popup<>background<>content script communication
Git & PR Workflow	references/git-workflow.md	Branching, committing, opening PRs, CI
Dependencies	references/dependencies.md	Adding, updating, or auditing packages
Anti-Patterns	references/anti-patterns.md	Code review, avoiding common mistakes
Troubleshooting	../../docs/troubleshooting-guide.md	Build failures, setup issues, known bugs and gotchas