Clone the Supamode Repository

Set up Supamode on your local machine. Clone the repository, install dependencies, and configure git remotes for updates.

This guide walks you through cloning the Supamode repository and setting up your development environment. The process takes about 5 minutes.

Prerequisites

Before starting, ensure you have:

Requirement	Version	Purpose
Node.js	20.x or later	JavaScript runtime
pnpm	10.x or later	Package manager (faster than npm)
Docker	Latest	Runs Supabase locally
Git	Latest	Version control

Optional: A Supabase account if you want to connect to a remote project (not required for local development).

Install pnpm

If you don't have pnpm installed:

npm install -g pnpm

Verify the installation:

pnpm --version
# Expected: 10.x.x or higher

Quick Setup (Recommended)

The fastest way to get started is using our CLI tool:

npx create-supamode-app@latest

This command:

Clones the repository using SSH
Installs all dependencies
Runs the interactive setup wizard
Configures environment variables

SSH Required

The automatic setup uses SSH to clone. If you haven't configured SSH keys with GitHub, use the manual setup below instead.

After the CLI completes, skip to Running Supamode.

Manual Setup

Use manual setup if you prefer HTTPS authentication or need more control over the process.

Step 1: Clone the Repository

Using SSH (recommended if configured):

git clone git@github.com:makerkit/supamode.git
cd supamode

Using HTTPS:

git clone https://github.com/makerkit/supamode.git
cd supamode

Step 2: Install Dependencies

pnpm install

This installs dependencies for all packages in the monorepo. The first install may take a few minutes.

Step 3: Run the Setup Wizard

pnpm turbo gen setup

The wizard prompts you to configure:

Site URL for local development
Supabase connection details
OAuth providers (optional)

Configure Git Remotes for Updates

Supamode receives regular updates. Configure your git remotes to pull updates while maintaining your own repository.

Remove the Default Origin

git remote rm origin

Add Upstream for Updates

SSH:

git remote add upstream git@github.com:makerkit/supamode.git

HTTPS:

git remote add upstream https://github.com/makerkit/supamode.git

Add Your Own Repository

Create a new repository on GitHub (or your preferred host), then:

git remote add origin git@github.com:YOUR_USERNAME/YOUR_REPO.git
git push -u origin main

Pull Updates

Pull updates regularly to get new features and bug fixes:

git pull upstream main

Update Strategy

We recommend pulling updates at least weekly. Before pulling, commit or stash your local changes. If you encounter merge conflicts, they're typically in configuration files that you can resolve by keeping your customizations.

Platform-Specific Notes

Windows

Place the repository near your drive root (e.g., C:\supamode) to avoid path length issues. Windows has a 260-character path limit that can cause module loading errors with deeply nested node_modules.

Avoid:

OneDrive folders (sync conflicts with node_modules)
Paths with spaces
Deep directory nesting

macOS / Linux

No special considerations. The repository works in any directory.

Verify Installation

After setup, verify everything is working:

# Check Node version
node --version
# Expected: v20.x.x or higher
# Check pnpm version
pnpm --version
# Expected: 10.x.x or higher
# Check Docker is running
docker info
# Expected: No errors
# List installed packages
pnpm list --depth=0
# Expected: Shows workspace packages

Project Structure

After cloning, you'll see this structure:

supamode/
├── apps/
│   ├── app/          # React frontend (Vite + React Router)
│   ├── api/          # Hono.js backend API
│   └── e2e/          # Playwright tests
├── packages/
│   ├── features/     # Feature modules (auth, data-explorer, etc.)
│   ├── supabase/     # Supabase client and Drizzle schema
│   └── ui/           # Shared UI components
├── tooling/          # ESLint, Prettier, TypeScript configs
└── turbo.json        # Turborepo configuration

Next Steps

Run the project to start the development servers
Seed demo data to explore the interface
Configure environment variables for your Supabase project

Troubleshooting

`EACCES` Permission Errors

If you see permission errors during pnpm install:

sudo chown -R $(whoami) ~/.pnpm-store

SSH Authentication Failed

If SSH fails, switch to HTTPS:

git remote set-url upstream https://github.com/makerkit/supamode.git

Docker Not Running

If Docker commands fail, ensure Docker Desktop is running. On Linux, you may need to start the daemon:

sudo systemctl start docker

Module Not Found Errors

Clear the pnpm cache and reinstall:

pnpm store prune
rm -rf node_modules
pnpm install