Skip to main content

​
Welcome Contributors

Thank you for your interest in contributing to Meelio! This guide will help you get started with contributing to our productivity and focus application. Meelio is built as a Turborepo monorepo with a fully offline-first architecture where all data is stored locally.

​
Code of Conduct

We are committed to providing a welcoming and inclusive experience for everyone. We expect all contributors to:
  • Be respectful and considerate in communication
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members
  • Avoid harassment, discrimination, or inappropriate behavior

​
Getting Started

1

Fork and Clone

Fork the repository on GitHub and clone your fork locally:
git clone https://github.com/YOUR_USERNAME/meelio.git
cd meelio
2

Install Dependencies

Meelio uses pnpm as the package manager. Install dependencies:
pnpm install
Requirements: Node.js >= 22.0.0 and pnpm 9.15.4 (specified in package.json)
3

Create a Branch

Create a new branch for your feature or fix:
git checkout -b feature/your-feature-name
4

Make Your Changes

Make your changes following our code style guidelines (see below).
5

Test Your Changes

Run linting and tests before submitting:
pnpm lint
pnpm test
6

Commit and Push

Commit your changes following our commit conventions and push to your fork.
7

Open a Pull Request

Open a pull request against the main repository with a clear description of your changes.

​
Development Workflow

​
Running in Development Mode

# Run all apps in development mode
pnpm dev

# Run only the web app
cd apps/web && pnpm dev

# Run only the extension
cd apps/extension && pnpm dev
The web app runs on port 4000 by default (http://localhost:4000)

​
Available Commands

CommandDescription
pnpm devRun all apps in development mode
pnpm buildBuild all apps
pnpm build:webBuild only the web app
pnpm build:extensionBuild only the extension
pnpm lintLint all packages
pnpm formatFormat code with Prettier
pnpm testRun all tests
pnpm cleanClean build artifacts

​
Code Style and Linting

Meelio enforces code quality through ESLint and Prettier.

​
ESLint Configuration

The project uses TypeScript ESLint with React-specific rules:
  • Base config: eslint:recommended
  • TypeScript: plugin:@typescript-eslint/recommended
  • React: plugin:react-hooks/recommended
  • React Refresh: Enforces proper component exports

​
Running Linters

# Lint all packages
pnpm lint

# Lint with max warnings set to 0 (fails on any warnings)
cd apps/web && pnpm lint
The web app uses --max-warnings 0 which means any ESLint warnings will cause the lint command to fail. Fix all warnings before submitting.

​
Code Formatting

Meelio uses Prettier for consistent code formatting: 
# Format all TypeScript, TSX, and Markdown files
pnpm format
Prettier Plugins Used:
  • @ianvs/prettier-plugin-sort-imports - Automatically sorts imports
  • prettier-plugin-tailwindcss - Sorts Tailwind CSS classes
Prettier is configured at the repository level and shared via @repo/prettier-config package.

​
Commit Conventions

We follow conventional commit messages for clarity and automated changelog generation:

​
Format

type(scope): subject

body (optional)

footer (optional)

​
Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, missing semicolons, etc.)
  • refactor: Code refactoring without feature changes
  • perf: Performance improvements
  • test: Adding or updating tests
  • chore: Maintenance tasks, dependency updates
  • build: Build system or dependency changes
  • ci: CI/CD configuration changes

​
Examples

feat(timer): add custom interval presets

fix(extension): resolve tab stash sync issue

docs(readme): update installation instructions

refactor(stores): simplify task state management

​
Pull Request Process

1

Ensure Quality

  • All tests pass (pnpm test)
  • No linting errors (pnpm lint)
  • Code is formatted (pnpm format)
  • Build succeeds (pnpm build)
2

Write Clear Description

Provide a clear description of:
  • What changes you made
  • Why you made them
  • Any breaking changes
  • Screenshots (if UI changes)
3

Link Issues

Reference any related issues using Fixes #123 or Relates to #456
4

Wait for Review

Maintainers will review your PR and may request changes.
5

Address Feedback

Make requested changes and push updates to your branch.
6

Merge

Once approved, a maintainer will merge your PR.

​
Project Structure Overview

Understanding the monorepo structure will help you navigate the codebase:

​
Apps

apps/
├── web/              # Vite + React web application
│   ├── src/          # Web app source code
│   ├── public/       # Static assets
│   └── e2e/          # Playwright tests (if configured)
│
└── extension/        # Plasmo browser extension
    ├── src/          # Extension source code
    ├── assets/       # Extension assets
    └── build/        # Built extension (gitignored)

​
Packages

packages/
├── shared/           # Core business logic, stores, hooks, components
│   ├── components/   # Shared React components
│   ├── hooks/        # Custom React hooks
│   ├── stores/       # Zustand state stores
│   ├── types/        # TypeScript type definitions
│   └── utils/        # Utility functions
│
├── ui/               # shadcn/ui based component library
├── logger/           # Logging utility
├── eslint-config/    # Shared ESLint configuration
├── typescript-config/# Shared TypeScript configuration
├── tailwind-config/  # Shared Tailwind CSS configuration
└── prettier-config/  # Shared Prettier configuration

​
Key Directories in @repo/shared

  • components/ - Reusable React components
  • hooks/ - Custom hooks for state and side effects
  • stores/ - Zustand stores for global state management
  • types/ - TypeScript interfaces and types
  • utils/ - Helper functions and utilities
  • lib/ - Third-party library configurations
  • data/ - Static data and constants
  • services/ - Business logic and services
  • i18n/ - Internationalization files

​
Finding Issues to Work On

Look for issues labeled:
  • good first issue - Great for newcomers
  • help wanted - Contributions welcome
  • bug - Bug fixes needed
  • enhancement - Feature requests

​
Questions?

If you have questions:
  • Check existing issues and discussions
  • Open a new discussion on GitHub
  • Review the documentation

​
License

By contributing to Meelio, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to Meelio! Your efforts help make productivity tools better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us