mirrors/mue
1
0
Fork 0
mirror of https://github.com/mue/mue.git synced 2026-07-13 04:02:32 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
7dec0a844e35242a101ee1a16aa1cc09b8e488d7
mue/CLAUDE.md
David Ralph 9040766fe3 chore: capitalise claude.md 
Signed-off-by: David Ralph <ohlookitsderpy@protonmail.com>
2026-02-02 16:52:31 +00:00

7.1 KiB
Raw Blame History

Mue Development Guide

Mue is a fast, open-source new tab page browser extension for Chrome, Firefox, and Safari.

Tech Stack

Core Technologies

  • React 19 - Modern hooks and functional components only
  • Vite 7 - Build tool with SWC for fast compilation
  • Bun - Package manager and JavaScript runtime (>= 1.3.0)
  • SCSS - Styling with modern compiler API
  • Browser Extension (Manifest V3) - Multi-browser support (Chrome, Firefox, Safari)

Key Libraries

  • @dnd-kit - Drag and drop functionality for widgets
  • @eartharoid/i18n - Internationalization with multiple locales
  • @sentry/react - Error tracking and monitoring
  • react-modal - Accessible modal dialogs
  • react-toastify - Toast notifications
  • IndexedDB & localStorage - Client-side data persistence
  • Vite path aliases - Imports use @/, components/, hooks/, utils/, etc.

Development Tools

  • ESLint - JavaScript/JSX linting with React plugin
  • Stylelint - SCSS/CSS linting
  • Prettier - Code formatting
  • Commitlint - Conventional commit enforcement
  • Husky - Git hooks for pre-commit checks

Project Structure

src/
├── components/     # Reusable UI components
├── features/       # Feature-specific components (quote, greeting, weather, etc.)
├── contexts/       # React Context providers for shared state
├── hooks/          # Custom React hooks
├── utils/          # Utility functions and helpers
├── lib/            # Third-party library wrappers
├── i18n/           # Internationalization and locale files
├── scss/           # Global styles, variables, and mixins
├── config/         # Configuration files
└── assets/         # Static assets (icons, images)

Development Rules

1. Translation Files

en_GB.json is the base translation file.

When updating translations:

  1. Edit src/i18n/locales/en_GB.json first
  2. Run bun run translations to sync changes to all locales
  3. This ensures formatting remains consistent across all language files

Available translation scripts:

  • bun run translations - Sync all locale files with en_GB
  • bun run translations:percentages - Update completion percentages
  • bun run translations:unused - Find unused translation keys

2. Branch Strategy

Use the three-branch workflow:

  • dev - Active development (target for all PRs)
  • beta - Release candidates for testing
  • main - Production/stable releases

Always create PRs targeting the dev branch.

3. Commit Messages

Follow conventional commits format:

  • feat: - New features
  • fix: - Bug fixes
  • chore: - Maintenance tasks
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Test-related changes
  • style: - Code style changes (formatting, etc.)

Commitlint will enforce this in pre-commit hooks.

4. Code Style & Quality

Before committing:

bun run lint:fix    # Auto-fix ESLint and Stylelint issues
bun run pretty      # Format code with Prettier

Linting rules:

  • Follow ESLint configuration in eslint.config.js
  • SCSS follows Stylelint standard SCSS rules
  • Husky pre-commit hooks will block commits with linting errors

5. Commenting

Do not add comments to the codebase. Keep code clean and self-explanatory. Use descriptive variable/function names instead of comments.

6. Package Manager

Always use Bun (not npm or yarn):

bun install         # Install dependencies
bun run dev         # Start dev server
bun run build       # Production build

7. Build Targets

The project builds for multiple browsers:

  • Chrome/Edge (Chromium)
  • Firefox
  • Safari (via Xcode)

Test changes across all targets when modifying:

  • Core functionality
  • Manifest files (manifest/chrome.json, manifest/firefox.json)
  • Browser-specific APIs

Build outputs:

  • dist/ - Vite bundled output
  • build/chrome/ - Chrome extension
  • build/firefox/ - Firefox extension
  • safari/Mue Extension/Resources/ - Safari extension

8. State Management

  • Persistent settings - Use localStorage via custom hooks
  • Shared state - Use React Context (see src/contexts/)
  • Component state - Use useState, useReducer for local state
  • Custom hooks - Create hooks for reusable stateful logic

9. Styling Conventions

SCSS files are organized in src/scss/:

  • _variables.scss - Color palette, breakpoints, sizes
  • _mixins.scss - Reusable style mixins
  • Component styles - Co-located in feature/component folders

Use existing variables and mixins for consistency.

10. Development Server

bun run dev         # Local development with HMR at localhost
bun run dev:host    # Expose on network for testing on other devices

Hot Module Replacement (HMR) is enabled for fast development.

11. Path Aliases

Use configured path aliases instead of relative imports:

// Good
import Button from 'components/Button';
import { useLocalStorageState } from 'hooks/useLocalStorageState';
import { getWeather } from 'utils/api';

// Avoid
import Button from '../../../components/Button';

Available aliases: @/, components/, contexts/, hooks/, assets/, config/, features/, lib/, scss/, translations/, utils/

12. Error Handling

  • Sentry is integrated for error tracking
  • Use ErrorBoundary component for React error boundaries
  • Handle async errors gracefully with try/catch
  • Show user-friendly error messages via react-toastify

13. Browser Extension Best Practices

  • Use Manifest V3 APIs (not deprecated V2 APIs)
  • Test extension loading/unloading
  • Handle permissions properly
  • Use background.js for background tasks
  • Store data in localStorage or IndexedDB, not sync storage
  • Ensure cross-browser compatibility (check MDN for API support)

14. Internationalization (i18n)

  • Use @eartharoid/i18n for translations
  • Access translations via the i18n context
  • Add new keys to en_GB.json first
  • Test with multiple locales to ensure proper rendering
  • Support RTL languages where applicable

15. Performance

  • Lazy load components where appropriate
  • Optimize images (use modern formats like WebP)
  • Minimize bundle size (check Vite build output)
  • Use useMemo and useCallback judiciously (only when needed)
  • Profile performance with React DevTools

Common Tasks

Adding a New Feature

  1. Create feature folder in src/features/
  2. Add components, hooks, and styles
  3. Update translations in en_GB.json
  4. Run bun run translations to sync locales
  5. Add tests if applicable
  6. Run bun run lint:fix and bun run pretty
  7. Commit with conventional commit message
  8. Create PR targeting dev branch

Debugging

  • Use React DevTools for component inspection
  • Check browser console for errors
  • Use Sentry for production error tracking
  • Test in all supported browsers

Testing on Browsers

  1. Run bun run build
  2. Load unpacked extension from build/chrome/ or build/firefox/
  3. For Safari, open Xcode project and build from there

Resources

Reference in New Issue View Git Blame Copy Permalink