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:

extension/ -- the browser extension itself (popup, background service worker, content scripts)
@stellar/freighter-api/ -- the npm SDK that dApps use to interact with Freighter
@shared/ -- shared packages (api, constants, helpers) consumed by multiple workspaces
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

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:

extension/ -- the browser extension itself (popup, background service worker, content scripts)

@stellar/freighter-api/ -- the npm SDK that dApps use to interact with Freighter

@shared/ -- shared packages (api, constants, helpers) consumed by multiple workspaces

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