Contributing to Nanobrowser

We deeply appreciate your interest in contributing! Every contribution helps make Nanobrowser more powerful and accessible for everyone. This guide provides detailed instructions for setting up your development environment and submitting your changes.

Setting Up the Development Environment

Prerequisites

Before you begin, ensure you have the following installed:

Node.js: Version 22.12.0 is required. We strongly recommend using a version manager like nvm. To switch to the correct version, run:
```
nvm use
```
pnpm: This project uses pnpm as its package manager. The required version is 9.15.1 or higher. Install it globally:
```
npm install -g pnpm
```

Installation

Fork and clone the repository:

git clone https://github.com/YOUR_USERNAME/nanobrowser.git
cd nanobrowser

Install all dependencies using pnpm:
```
pnpm install
```

Core Development Commands

All commands should be run from the root of the project.

Start Development Mode: This command starts Vite in watch mode with hot reload for all packages.
```
pnpm dev
```
After running this, load the dist/ directory as an unpacked extension in Chrome to see your changes.
Build for Production: This command creates an optimized production build in the dist/ directory.
```
pnpm build
```
Run Type Checking: Check for any TypeScript errors across the project.
```
pnpm type-check
```
Run Linter: Check for code style issues and automatically fix them.
```
pnpm lint
```
Format Code: Format all code using Prettier.
```
pnpm prettier
```
Create Extension Zip: Build the project and create a distributable .zip file in the dist-zip/ directory.
```
pnpm zip
```

Workspace-Scoped Commands

To speed up development, you can run commands scoped to a specific workspace. This is much faster than running them across the entire monorepo.

# Build only the side-panel UI
pnpm -F side-panel build

# Run the linter on a single file in the chrome-extension package
pnpm -F chrome-extension lint -- src/background/index.ts

# Run TypeScript checks for the storage package
pnpm -F packages/storage type-check

Running Tests

Unit Tests (Vitest): Tests for the core extension logic are located in the chrome-extension package.

# Run all unit tests
pnpm -F chrome-extension test

# Run a specific test file or suite
pnpm -F chrome-extension test -- -t "Sanitizer"

End-to-End Tests: This command first builds the project and zips it, then runs the E2E tests.
```
pnpm e2e
```

Code Quality and Standards

Formatting: Code is formatted by Prettier. Please run pnpm prettier before committing.
Linting: We use ESLint with strict rules for TypeScript, React, accessibility, and imports. Run pnpm lint to check your code.
Type Safety: Leverage TypeScript's type system to ensure code is reliable and maintainable. Always run pnpm type-check before submitting a pull request.
Commit Messages: Write clear commit messages in the present tense (e.g., "Add feature" not "Added feature").

Internationalization (i18n)

We use a structured system for managing translations. All locale files are located in packages/i18n/locales/.

Key Naming Convention: Follow the pattern component_category_specificAction_state (e.g., chat_input_placeholder, act_click_ok).
Adding Translations: To add or modify translations, edit the JSON files in the appropriate locale directory. Do not edit files under packages/i18n/lib/, as they are auto-generated.
Generating Types: After modifying the locale files, the i18n types and helpers are automatically regenerated during the build process (pnpm dev or pnpm build).

Submitting Changes

Create a new branch for your feature or bug fix: git checkout -b feature-name.
Make your changes, adhering to the code quality standards.
Test your changes thoroughly.
If you add new user-facing features, update the documentation.
Submit a Pull Request with a clear description of your changes.
Be responsive to feedback and address review comments promptly.

Thank you for contributing!