Development Setup
This guide will help you set up a local development environment for contributing to MagicSync.
Prerequisites
Before you begin, ensure you have the following installed:
- Node.js: v20.0.0 or higher
- pnpm: v10.19.0 or higher
- Git: Latest version
Initial Setup
1. Fork and Clone
First, fork the repository on GitHub, then clone your fork:
git clone https://github.com/YOUR_USERNAME/magicsync.git
cd magicsync2. Enable Corepack
Corepack ensures you use the correct package manager version:
corepack enable3. Install Dependencies
Install all project dependencies:
pnpm installThis installs dependencies for all workspace packages.
4. Set Up Environment Variables
cp .env-example .envEdit .env with your configuration. See Platform Keys for obtaining API keys.
Development Workflow
Running the Development Server
Start all development servers:
pnpm site:devAccess the application at http://localhost:3000
Running Individual Packages
# Database layer
cd packages/db && pnpm dev
# Agent layer (includes its playground)
cd packages/agent && pnpm dev
# UI layer
cd packages/ui && pnpm dev
# Documentation
cd packages/doc && pnpm devBuilding for Production
# Build all packages
pnpm build
# Build main site
pnpm site:buildDatabase Setup
MagicSync uses Turso (libSQL) with Drizzle ORM.
Generate Database Migrations
cd packages/db
pnpm db:generateApply Migrations
cd packages/db
pnpm db:migrateProject Structure
magicsync/
├── packages/
│ ├── db/ # Database layer
│ │ ├── server/
│ │ │ ├── services/ # Business logic & plugins
│ │ │ └── database/ # Schemas & migrations
│ │ └── package.json
│ ├── auth/ # Authentication layer
│ ├── ui/ # UI components (Nuxt UI wrappers)
│ ├── assets/ # Static assets
│ ├── scheduler/ # Post scheduling
│ ├── bulk-scheduler/ # Bulk operations
│ ├── connect/ # Platform OAuth
│ ├── tools/ # In-browser tools
│ ├── ai-tools/ # AI content generation, LLM config, chat UI
│ ├── agent/ # Agent runtime (pi SDK, tools, workflows, RAG, PII)
│ ├── content/ # Blog & static content
│ ├── email/ # Email templates
│ ├── shared/ # Shared types & services
│ ├── templates/ # Content templates
│ ├── python-tools/ # Optional Python tools sidecar (FastAPI)
│ ├── site/ # Main application (layer merge point)
│ └── doc/ # Documentation (VitePress)
├── .env-example # Environment template
├── pnpm-workspace.yaml # pnpm workspace config
└── package.json # Root package.jsonLayer Package Commands
| Layer | Dev Command |
|---|---|
| site | pnpm site:dev |
| db | cd packages/db && pnpm dev |
| agent | cd packages/agent && pnpm dev |
| ui | cd packages/ui && pnpm dev |
| doc | cd packages/doc && pnpm dev |
| python-tools (optional) | pnpm python-tools:dev |
Code Quality
Linting
Each package exposes its own ESLint script:
pnpm --filter @local-monorepo/site lint
pnpm --filter @local-monorepo/db lintNote:
typescript-eslintdoes not yet support TypeScript 7, so the root lint toolchain fails repo-wide until the pinned toolchain catches up. The per-task verification gate therefore uses the test suites andvite-doctorinstead.
Structural Diagnostics
pnpm dlx vite-doctor .New code must not add findings. The only remaining diagnostics are pre-existing ones in packages/db and packages/scheduler.
Tests
# Database services + schema (migrated file SQLite)
pnpm --filter @local-monorepo/db test:services
# Agent layer (stub provider; no network or API keys)
pnpm --filter @local-monorepo/agent test
# Production build (catches route/page regressions)
pnpm site:buildDebugging
Debugging API Routes
- Check server logs in the terminal
- Use Nuxt DevTools (automatically available in dev mode)
- Add
console.log()statements inpackages/*/server/api/
Debugging Platform Integrations
When working on platform plugins in packages/*/server/services/:
- Check the plugin file for the specific platform
- Verify API credentials in
.env - Use the platform's API documentation for reference
Debugging Database Issues
- Check the schema in
packages/db/server/database/schema/ - Verify migrations in
packages/db/drizzle/ - Use Drizzle Studio:
cd packages/db && pnpm db:studio
Common Issues
Port Already in Use
# Find and kill the process
lsof -ti:3000 | xargs kill -9
# Or use a different port
PORT=3001 pnpm site:devEnvironment Variables Not Loading
- Ensure
.envexists in the root directory - Restart the dev server
- Check that variables are prefixed with
NUXT_for Nuxt runtime config
Database Connection Errors
- Check
DATABASE_URLin.env - For Turso, verify your auth token
- For local development, ensure the database file path is writable
Next Steps
Now that you have your development environment set up:
- Read the Architecture guide
- Learn about Adding Features
- Check the Documentation guide
Getting Help
If you encounter issues:
- Check existing GitHub Issues
- Open a new issue with details
- Ask in GitHub Discussions