Local Development Setup

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version: 18.x or higherDownload Node.js

Package Manager

Options: npm, yarn, pnpm, or bunComes with Node.js (npm)

Git

Version: 2.x or higherDownload Git

Code Editor

Recommended: VS CodeDownload VS Code

Verify Installation

Check Node.js Version

node --version
# Should output v18.x.x or higher

Check npm Version

npm --version
# Should output 9.x.x or higher

Check Git Version

git --version
# Should output git version 2.x.x

Supabase Account Setup

You’ll need a Supabase project to run ClipSync locally. The app cannot function without a configured backend.

Create Supabase Project

Go to supabase.com
Click “Start your project”
Sign up with GitHub or email

Create New Project

Click “New Project”
Choose an organization (or create one)
Fill in project details:
- Name: ClipSync (or any name)
- Database Password: Generate a strong password
- Region: Choose closest to you
Click “Create new project”
Wait for project to finish setting up (~2 minutes)

Get API Credentials

Navigate to Settings → API
Copy the following values:
- Project URL (under “Project URL”)
- anon public key (under “Project API keys”)

Keep these credentials safe! You’ll need them for the .env file.

Set Up Database Tables

Open SQL Editor

Navigate to SQL Editor in the left sidebar

Create Tables

Run the following SQL queries to create required tables:

CREATE TABLE sessions (
  id BIGSERIAL PRIMARY KEY,
  code VARCHAR(5) UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create index for faster lookups
CREATE INDEX idx_sessions_code ON sessions(code);

Enable Realtime

Enable realtime for the clipboard table:

Navigate to Database → Replication
Find the clipboard table
Toggle Enable Realtime to ON

Or run this SQL:

ALTER PUBLICATION supabase_realtime ADD TABLE clipboard;

Set Up Storage Bucket

Navigate to Storage

Go to Storage in the left sidebar

Create Bucket

Click “New bucket”
Name: clipboard
Public bucket: Toggle ON (files need to be publicly accessible)
Click “Create bucket”

Configure Bucket Policies

Set up storage policies to allow uploads and deletes:

Click on the clipboard bucket
Go to Policies tab
Add the following policies:

Allow Upload Policy

CREATE POLICY "Allow public uploads"
ON storage.objects FOR INSERT
TO public
WITH CHECK (bucket_id = 'clipboard');

Allow Public Access Policy

CREATE POLICY "Allow public access"
ON storage.objects FOR SELECT
TO public
USING (bucket_id = 'clipboard');

Allow Delete Policy

CREATE POLICY "Allow public deletes"
ON storage.objects FOR DELETE
TO public
USING (bucket_id = 'clipboard');

In a production environment, you would want to add authentication and restrict these policies to authenticated users only.

Project Setup

Clone Repository

Clone the Repo

git clone <repository-url>
cd clipsync

Replace <repository-url> with the actual repository URL.

Navigate to Client Directory

cd client

The client application is in the client/ subdirectory.

Install Dependencies

npm
yarn
pnpm
bun

npm install

yarn install

pnpm install

bun install

The project uses bun.lockb, suggesting Bun was used during development.

Reference: package.json:12-38

Environment Configuration

Create .env File

Create a .env file in the client/ directory:

touch .env

Add Environment Variables

Add your Supabase credentials to .env:

.env

VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Replace your_supabase_project_url and your_supabase_anon_key with the actual values from your Supabase project settings.

Update Storage URL (if needed)

If your Supabase project URL is different, update the storage URL in src/App.jsx:

src/App.jsx:156

const url = `https://YOUR_PROJECT_ID.supabase.co/storage/v1/object/public/${data.fullPath}`;

Replace YOUR_PROJECT_ID with your actual Supabase project ID.Reference: src/App.jsx:156

Reference: src/config/supabase.js:1-7

Verify Configuration

Check .env File

Ensure your .env file looks like this:

VITE_SUPABASE_URL=https://xxxxxxxxxxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Add to .gitignore

Ensure .env is in .gitignore to avoid committing secrets:

.gitignore

.env
.env.local
.env.production

Running Locally

Development Server

Reference: package.json:7

npm
yarn
pnpm
bun

npm run dev

yarn dev

pnpm dev

bun dev

Start Development Server

Run the dev command. You should see output like:

VITE v6.2.0  ready in 350 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

Open in Browser

Navigate to http://localhost:5173The app should load with the ClipSync interface.

Test Functionality

Enter some text in the clipboard textarea
Click “Send to Clipboard”
A session code should be generated
Verify the clipboard entry appears in the history

Hot Module Replacement (HMR) is enabled by default. Changes to your code will instantly reflect in the browser without a full reload.

Development Workflow

File Watching

Vite watches all files in src/ for changes. Save any file to see instant updates.

Error Handling

Errors appear both in the browser overlay and terminal console.

Network Access

To test on other devices (mobile, tablet), use:

npm run dev -- --host

Then access via your local IP (e.g., http://192.168.1.100:5173)

Build and Preview

Production Build

Reference: package.json:8

npm
yarn
pnpm
bun

npm run build

yarn build

pnpm build

bun run build

This command:

Runs type checking (if TypeScript is configured)
Bundles and minifies all assets
Optimizes images and fonts
Generates service worker for PWA
Outputs production-ready files to dist/

Build output typically includes:

HTML, CSS, JS files (minified & hashed)
Service worker
PWA manifest
Static assets (images, fonts, icons)

Preview Production Build

Reference: package.json:10

npm
yarn
pnpm
bun

npm run preview

yarn preview

pnpm preview

bun preview

This starts a local server serving the built files from dist/.

The preview server is for local testing only. Do not use it in production.

Lint Code

Reference: package.json:9

npm
yarn

npm run lint

yarn lint

Runs ESLint to check for code quality issues and style violations. Reference: eslint.config.js:7-38

Development Tips

VS Code Extensions

ESLint

ID: dbaeumer.vscode-eslintHighlights linting errors in real-time

Tailwind CSS IntelliSense

ID: bradlc.vscode-tailwindcssAutocomplete for Tailwind classes

ES7+ React Snippets

ID: dsznajder.es7-react-js-snippetsReact code snippets and shortcuts

Prettier

ID: esbenp.prettier-vscodeCode formatting on save

Browser DevTools

React DevTools
Network Tab
Application Tab

Install the React DevTools browser extension to:

Inspect component tree
View component props and state
Profile performance

Testing Realtime Sync

Open Multiple Tabs

Open ClipSync in 2+ browser tabs or windows

Join Same Session

Use the same session code in all tabs

Test Sync

Add clipboard content in one tab and watch it appear instantly in others

Test Delete

Delete an item in one tab and verify it disappears in all tabs

Testing Offline Mode

Open DevTools

Press F12 to open browser DevTools

Simulate Offline

Go to Network tab
Change throttling to “Offline”
Reload the page

Verify Offline Banner

You should see the red “You are offline” banner

Go Back Online

Change throttling back to “Online”
The app should reconnect automatically
Clipboard history should refetch

Reference: src/App.jsx:40-53

Common Development Issues

Port Already in Use

Error: Port 5173 is already in useSolution:

# Kill process on port 5173 (macOS/Linux)
lsof -ti:5173 | xargs kill -9

# Or use a different port
npm run dev -- --port 3000

Supabase Connection Failed

Error: Network errors when loading the appSolution:

Verify .env variables are correct
Check Supabase project is running (not paused)
Ensure you’re using the correct API URL (not the reference ID)
Restart the dev server after changing .env

Realtime Not Working

Error: Changes don’t sync between tabsSolution:

Verify Realtime is enabled for the clipboard table
Check browser console for WebSocket errors
Ensure both tabs are using the same session code
Check Supabase realtime quota (free tier has limits)

File Upload Fails

Error: File upload returns 403 or 401Solution:

Verify storage bucket clipboard exists
Check bucket policies allow public uploads
Ensure bucket is set to public
Update hardcoded storage URL in src/App.jsx:156

Next Steps

Architecture

Learn about the system architecture

Contributing

Guidelines for contributing to ClipSync

Tech Stack

Deep dive into technologies used

Getting Started

Core Features

Guides

Development

​Prerequisites

Node.js

Package Manager

Git

Code Editor

​Verify Installation

​Supabase Account Setup

​Create Supabase Project

​Set Up Database Tables

​Set Up Storage Bucket

​Project Setup

​Clone Repository

​Install Dependencies

​Environment Configuration

​Verify Configuration

​Running Locally

​Development Server

​Development Workflow

​Build and Preview

​Production Build

​Preview Production Build

​Lint Code

​Development Tips

​VS Code Extensions

ESLint

Tailwind CSS IntelliSense

ES7+ React Snippets

Prettier

​Browser DevTools

​Testing Realtime Sync

​Testing Offline Mode

​Common Development Issues

​Next Steps

Architecture

Contributing

Tech Stack

Build docs developers (and LLMs) love

Prerequisites

Verify Installation

Supabase Account Setup

Create Supabase Project

Set Up Database Tables

Set Up Storage Bucket

Project Setup

Clone Repository

Install Dependencies

Environment Configuration

Verify Configuration

Running Locally

Development Server

Development Workflow

Build and Preview

Production Build

Preview Production Build

Lint Code

Development Tips

VS Code Extensions

Browser DevTools

Testing Realtime Sync

Testing Offline Mode

Common Development Issues

Next Steps