Installation

Set up ClipSync locally for development with this comprehensive installation guide

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

1. Install Bun

   ClipSync requires Bun to be installed on your system.

   macOS/Linux

   curl -fsSL https://bun.sh/install | bash
   

   Verify the installation:

   bun --version
   
2. Set up Supabase

   ClipSync uses Supabase for backend services. You’ll need:

   1. A Supabase account (free tier works fine)
   2. A new Supabase project
   3. Your project’s URL and anon key

   Get your credentials from your Supabase project dashboard under Settings > API.

Clone the Repository

1. Clone the repo

   git clone <repository-url>
   cd client
   

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

Environment Configuration

1. Create environment file

   Create a .env file in the client directory:

   touch .env
   
2. Add environment variables

   Add the following variables to your .env file:

   .env

   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.

   Example:

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

Database Setup

1. 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()
   );
   

   Clipboard table:

   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()
   );
   

   Counter table (for visitor tracking):

   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);
   
2. Set up Storage bucket

   Create a storage bucket named clipboard in your Supabase Storage:

   1. Go to Storage in your Supabase dashboard
   2. Click New bucket
   3. Name it clipboard
   4. Set it to Public for file access
   5. Configure bucket policies for public read access
3. Enable Realtime

   Enable real-time for the clipboard table:

   1. Go to Database > Replication
   2. Enable replication for the clipboard table

   Real-time subscriptions are used to sync clipboard content across devices instantly.

Install Dependencies

1. Install packages

   Install all required dependencies:

   bun install
   

   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

1. Start the dev server

   Development

   bun run dev
   

   The application will be available at http://localhost:5173 (default Vite port).

2. 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:

vite.config.js

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:

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

Real-time not working

• Verify real-time is enabled for the clipboard table
• Check browser console for WebSocket connection errors
• Ensure you’re using the correct session code

File upload failing

• 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.