Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 22.0.0 or higher is required

pnpm

Version 9.15.4 (specified in package.json)
Meelio uses a Turborepo monorepo structure with pnpm workspaces. Make sure you have pnpm installed globally:
npm install -g [email protected]

​
Installation

1

Clone the repository

git clone https://github.com/yourusername/meelio.git
cd meelio
2

Install dependencies

Install all dependencies for the monorepo using pnpm:
pnpm install
This will install dependencies for all apps and packages in the workspace.
3

Start development servers

Run all apps in development mode:
pnpm dev
This starts:
  • Web app on http://localhost:4000
  • Extension in development mode with Plasmo

​
Available Commands

All commands are run from the root directory: 
# Run all apps in dev mode
pnpm dev

​
Loading the Extension Locally

1

Build the extension

pnpm build:extension
This creates a production build in apps/extension/build/chrome-mv3-prod
2

Open Chrome Extensions

Navigate to chrome://extensions in your Chrome browser
3

Enable Developer Mode

Toggle the Developer mode switch in the top right corner
4

Load the extension

Click Load unpacked and select the directory:
apps/extension/build/chrome-mv3-prod
For development, you can also use pnpm dev which runs Plasmo in watch mode and automatically reloads the extension on changes.

​
Development Workflow

​
Working on the Web App

The web app is located in apps/web/ and runs on port 4000: 
# From root directory
pnpm dev

# Or run only the web app
cd apps/web
pnpm dev
The dev server supports:
  • Hot Module Replacement (HMR)
  • React Fast Refresh
  • Automatic TypeScript type checking

​
Working on the Extension

The extension uses Plasmo framework and is located in apps/extension/: 
# Development mode with hot reload
pnpm dev

# Build for specific browsers
cd apps/extension
pnpm build:chrome
pnpm build:firefox
pnpm build:edge

​
Working on Shared Packages

The monorepo includes several shared packages in packages/:
  • @repo/shared - Core business logic, stores, hooks, components
  • @repo/ui - React component library (shadcn/ui based)
  • @repo/logger - Logging utility
  • Configuration packages (ESLint, TypeScript, Tailwind, Prettier)
Changes to packages are automatically picked up by Turborepo’s build pipeline.

​
Turborepo Tasks

The monorepo uses Turborepo for task orchestration. Key tasks are defined in turbo.json:
Builds all apps and packages. Outputs include:
  • dist/** - Compiled output
  • build/** - Extension builds
  • .next/** - Next.js builds (if applicable)
Dependencies are built first via dependsOn: ["^build"]
Runs development servers. This is a persistent task that doesn’t cache.
Lints all packages. Depends on packages being built first.
Runs test suites and generates coverage reports in coverage/**

​
Environment Variables

Meelio is designed to be fully offline-first, so most features work without external APIs. However, some optional features may require environment variables. Create .env files in the respective app directories: 
# apps/web/.env
VITE_APP_VERSION=0.8.2

# apps/extension/.env
# Extension-specific variables (if any)
Never commit .env files to version control. They are already included in .gitignore.

​
Troubleshooting

​
Port 4000 already in use

The web app runs on port 4000 by default (configured in apps/web/package.json): 
# Kill the process using port 4000
lsof -ti:4000 | xargs kill -9

# Or change the port in apps/web/package.json
"dev": "vite --port=4001"

​
pnpm install fails

Ensure you’re using the correct pnpm version: 
pnpm --version  # Should be 9.15.4

# If not, install the correct version
npm install -g [email protected]

​
Extension not loading

Make sure you built the extension first: 
pnpm build:extension
Then check that you’re loading the correct directory: 
apps/extension/build/chrome-mv3-prod

​
TypeScript errors

The project uses TypeScript 5.3.3. If you encounter type errors: 
# Clean and rebuild
pnpm clean
pnpm build

​
Next Steps

Architecture

Learn about Meelio’s architecture and design patterns

Contributing

Guidelines for contributing to Meelio

Build docs developers (and LLMs) love

Get started for freeTalk to us