Installation Guide
This guide will help you set up ClipSync locally for development. The project uses Bun as the JavaScript runtime and package manager.
Prerequisites
Install Bun
ClipSync requires Bun to be installed on your system.curl -fsSL https://bun.sh/install | bash
Set up Supabase
ClipSync uses Supabase for backend services. You’ll need:
- A Supabase account (free tier works fine)
- A new Supabase project
- Your project’s URL and anon key
Get your credentials from your Supabase project dashboard under Settings > API.
Clone the Repository
Clone the repo
git clone <repository-url>
cd client
Replace <repository-url> with the actual repository URL.
Environment Configuration
Create environment file
Create a .env file in the client directory: Add environment variables
Add the following variables to your .env file:VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
Never commit your .env file to version control. It’s already included in .gitignore.
VITE_SUPABASE_URL=https://qthpintkaihcmklahkwf.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Database Setup
Create database tables
In your Supabase project, create the following tables:Sessions table:CREATE TABLE sessions (
id BIGSERIAL PRIMARY KEY,
code VARCHAR(5) UNIQUE NOT NULL,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE TABLE clipboard (
id BIGSERIAL PRIMARY KEY,
session_code VARCHAR(5) NOT NULL,
content TEXT,
fileUrl TEXT,
file JSONB,
sensitive BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE TABLE counter (
id INTEGER PRIMARY KEY,
total INTEGER DEFAULT 0,
unique INTEGER DEFAULT 0
);
INSERT INTO counter (id, total, unique) VALUES (1, 0, 0);
Set up Storage bucket
Create a storage bucket named clipboard in your Supabase Storage:
- Go to Storage in your Supabase dashboard
- Click New bucket
- Name it
clipboard
- Set it to Public for file access
- Configure bucket policies for public read access
Enable Realtime
Enable real-time for the clipboard table:
- Go to Database > Replication
- Enable replication for the
clipboard table
Real-time subscriptions are used to sync clipboard content across devices instantly.
Install Dependencies
Install packages
Install all required dependencies:This will install:
- React 19 and React DOM
- Supabase client library
- TanStack Query for data fetching
- Lucide React for icons
- Tailwind CSS for styling
- Vite PWA plugin for Progressive Web App features
- And other dependencies listed in
package.json
Run Development Server
Start the dev server
http://localhost:5173 (default Vite port).Verify installation
Open your browser and navigate to http://localhost:5173. You should see:
- The ClipSync interface
- Session code input field
- Clipboard textarea
- File upload buttons
Try creating a session and syncing content to ensure everything is working correctly.
Project Structure
The ClipSync client follows this structure:
client/
├── src/
│ ├── App.jsx # Main application component
│ ├── main.jsx # Application entry point
│ ├── config/
│ │ └── supabase.js # Supabase client configuration
│ ├── service/
│ │ └── doc.service.js # Session creation service
│ ├── utils/
│ │ └── index.js # Utility functions (link conversion, etc.)
│ └── compressedFileUpload.jsx # Image compression logic
├── public/ # Static assets and PWA icons
├── vite.config.js # Vite and PWA configuration
├── tailwind.config.js # Tailwind CSS configuration
├── package.json # Dependencies and scripts
└── .env # Environment variables (create this)
Configuration Files
Vite Configuration
The vite.config.js configures the PWA manifest:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { VitePWA } from 'vite-plugin-pwa'
export default defineConfig({
plugins: [
react(),
VitePWA({
registerType: 'autoUpdate',
workbox: {
globPatterns: ["**/*"],
},
manifest: {
"name": "ClipSync",
"short_name": "ClipSync",
"description": "A web app for syncing clipboard across devices.",
"start_url": "/",
"display": "standalone",
"theme_color": "#000000",
"background_color": "#000000"
}
})
]
})
Supabase Client
The Supabase client is configured in src/config/supabase.js:
import { createClient } from "@supabase/supabase-js";
const SUPABASE_URL = import.meta.env.VITE_SUPABASE_URL;
const SUPABASE_ANON_KEY = import.meta.env.VITE_SUPABASE_ANON_KEY;
const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
export default supabase;
Development Scripts
Available scripts in package.json:
| Command | Description |
|---|
bun run dev | Start development server with hot reload |
bun run build | Build for production |
bun run preview | Preview production build locally |
bun run lint | Run ESLint for code quality |
Troubleshooting
Environment variables not loading
- Ensure your
.env file is in the client root directory
- Restart the development server after adding environment variables
- Verify variables are prefixed with
VITE_
Supabase connection errors
- Verify your Supabase URL and anon key are correct
- Check that your Supabase project is active
- Ensure your IP is not blocked by Supabase
- Verify real-time is enabled for the clipboard table
- Check browser console for WebSocket connection errors
- Ensure you’re using the correct session code
- Confirm the
clipboard storage bucket exists and is public
- Check file size is under 10MB
- Verify storage bucket policies allow uploads
Next Steps
Quick Start
Learn how to use ClipSync
GitHub Repository
View the source code
For production deployment, consider using platforms like Cloudflare Pages, Vercel, or Netlify that support Vite applications.