mue/.github/.copilot-instructions.md

# Mue Project Guidelines for GitHub Copilot

## Project Overview

Mue is a fast, open-source browser extension that provides a customizable new tab page for Chrome, Firefox, Edge, and Safari. Built with React and Vite, it emphasizes privacy, performance, and extensibility.

## Technical Stack

- **Framework**: React 19 with hooks and functional components
- **Build Tool**: Vite with SWC
- **Package Manager**: Bun >= 1.3.0 (ALWAYS use Bun, never npm or yarn)
- **Styling**: SCSS with component-scoped styles
- **Target**: Browser extensions (Manifest V3)
- **Testing**: Manual testing across Chrome, Firefox, and Safari

## Code Style & Quality

- Follow ESLint configuration in `eslint.config.js`
- Run `bun run lint:fix` before committing
- Run `bun run pretty` to format code with Prettier
- Use conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, etc.
- All commits must pass commitlint validation

## File Organization

```
src/
├── components/     # Reusable UI components (Elements, Form, Layout)
├── features/       # Feature-specific code (background, weather, etc.)
├── utils/          # Utility functions and helpers
├── contexts/       # React Context providers
├── hooks/          # Custom React hooks
├── i18n/          # Internationalization files
└── scss/          # Global styles, variables, mixins
```

## Critical Rules

### 1. Translation Files (IMPORTANT!)

- **`en_GB.json` is the base translation file**
- Never edit other locale files directly
- Workflow: Edit `en_GB.json` → Run `bun run translations`
- This ensures consistent formatting across all 30+ locales
- Translation files are in `src/i18n/locales/`

### 2. Branch Strategy

```
dev (active development)
 ↓
beta (release candidates)
 ↓
main (production/stable)
```

- All PRs target the `dev` branch
- Never commit directly to `beta` or `main`
- See `CONTRIBUTING.md` for full workflow

### 3. Package Manager

- **ALWAYS use Bun**, never npm or yarn
- Commands: `bun install`, `bun run <script>`
- Project requires Bun >= 1.3.0

### 4. Multi-Browser Support

- Test changes in Chrome, Firefox, and Safari when possible
- Browser-specific builds are in `build/chrome/`, `build/firefox/`, etc.
- Manifest files: `manifest/chrome.json`, `manifest/firefox.json`

### 5. State Management

- Use `useLocalStorageState` hook for persistent settings
- Use React Context for shared state (see `src/contexts/`)
- Store user data in localStorage or IndexedDB (via `customBackgroundDB.js`)

### 6. Styling

- SCSS files in `src/scss/`
- Use existing variables from `_variables.scss`
- Use mixins from `_mixins.scss` (especially for responsive design)
- Mobile styles in `_mobile.scss`

## Development Commands

```bash
bun run dev              # Start dev server
bun run dev:host         # Dev server accessible on network
bun run build            # Build for production (all browsers)
bun run lint             # Run linters
bun run lint:fix         # Auto-fix linting issues
bun run pretty           # Format code
bun run translations     # Update translation files
```

## Common Patterns

### Component Structure

```jsx
import { useState } from 'react';
import './ComponentName.scss';

export default function ComponentName({ prop1, prop2 }) {
  const [state, setState] = useState();

  return <div className="component-name">{/* JSX content */}</div>;
}
```

### Using localStorage

```jsx
import { useLocalStorageState } from 'utils/useLocalStorageState';

const [value, setValue] = useLocalStorageState('settingKey', defaultValue);
```

### Using Translations

```jsx
import { useContext } from 'react';
import { TranslationContext } from 'contexts';

const { t } = useContext(TranslationContext);
const text = t('translation.key');
```

## Things to Avoid

- ❌ Don't use npm or yarn (use Bun)
- ❌ Don't edit locale files other than `en_GB.json`
- ❌ Don't commit directly to `beta` or `main` branches
- ❌ Don't introduce new dependencies without discussion
- ❌ Don't skip linting/formatting before commits
- ❌ Don't use class components (use functional components only)

## When Making Changes

1. Check which files need updates (component, styles, utils)
2. Follow existing patterns in similar components
3. Update translations in `en_GB.json` if adding new text
4. Run `bun run lint:fix` and `bun run pretty`
5. Test in at least Chrome and Firefox
6. Write conventional commit message

## Additional Resources

- See `CONTRIBUTING.md` for full contribution guidelines
- See `docs/RELEASE_PROCESS.md` for release procedures
- Check existing components in `src/components/` for patterns