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

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

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

import { useLocalStorageState } from 'utils/useLocalStorageState';

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

Using Translations

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