🚀 Bookmark Sync - Complete Setup Guide

This guide will help you set up the development environment, understand the project structure, and start contributing to Bookmark Sync.

Prerequisites
Initial Setup
Development Environment
Project Structure
Configuration
Development Workflow
Testing
Building for Production
Deployment
Troubleshooting

Prerequisites

Required Software

Web Browser
- Chrome 88+ / Edge 88+ (recommended for development)
- Firefox 109+ (for cross-browser testing)
Code Editor (Choose one)
- VS Code (recommended) - Download
- Sublime Text
- WebStorm
Git
- Download Git
- Basic Git knowledge recommended

Optional Tools

Node.js & npm (for future build tools)
- Download Node.js (LTS version recommended)
Extension Development Tools
- Chrome DevTools
- React Developer Tools (if you add React later)

Initial Setup

1. Clone the Repository

# Using HTTPS
git clone https://github.com/Sumon-Kayal/Bookmark-Sync.git

# Using SSH (if configured)
git clone git@github.com:Sumon-Kayal/Bookmark-Sync.git

# Navigate to project directory
cd Bookmark-Sync

2. Verify Files

Ensure all required files are present:

ls -la

You should see:

manifest.json
background.js
popup.html
popup.js
manager.html
styles.css
icons/ (containing icon16.png, icon32.png, icon48.png, icon128.png)
LICENSE
README.md
.gitignore

3. Create Missing Directories (if needed)

# Create icons directory
mkdir -p icons

Development Environment

VS Code Setup (Recommended)

Install VS Code Extensions
- ESLint
- Prettier - Code formatter
- JavaScript (ES6) code snippets
- Live Server
- GitLens
Create VS Code Workspace Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "files.eol": "\n",
  "javascript.preferences.quoteStyle": "single",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Create VS Code Extensions Recommendations

Create .vscode/extensions.json:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "xabikos.javascriptsnippets",
    "eamodio.gitlens"
  ]
}

Browser Setup

Chrome/Edge Setup

Open browser and navigate to:
- Chrome: chrome://extensions/
- Edge: edge://extensions/
Enable "Developer mode" (toggle in top-right)
Click "Load unpacked"
Select your Bookmark-Sync folder
Extension should now appear in your toolbar

Firefox Setup

Navigate to about:debugging#/runtime/this-firefox
Click "Load Temporary Add-on"
Navigate to your project folder
Select manifest.json
Extension is now loaded (temporary - will be removed on browser restart)

Project Structure

Current Structure

Bookmark-Sync/
│
├── manifest.json          # Extension configuration
├── background.js          # Background service worker
├── popup.html            # Popup UI
├── popup.js              # Popup logic
├── manager.html          # Manager UI
├── styles.css            # Styles
├── LICENSE               # GPL-3.0 License
├── README.md             # Documentation
└── .gitignore           # Git ignore file

Recommended Structure (Future Enhancement)

Bookmark-Sync/
│
├── src/
│   ├── background/
│   │   └── background.js
│   ├── popup/
│   │   ├── popup.html
│   │   ├── popup.js
│   │   └── popup.css
│   ├── manager/
│   │   ├── manager.html
│   │   ├── manager.js
│   │   └── manager.css
│   ├── common/
│   │   ├── utils.js
│   │   └── storage.js
│   └── styles/
│       └── global.css
│
├── assets/
│   ├── icons/
│   │   ├── icon16.png
│   │   ├── icon32.png
│   │   ├── icon48.png
│   │   └── icon128.png
│   └── images/
│
├── docs/
│   ├── API.md
│   └── CONTRIBUTING.md
│
├── tests/
│   └── (test files)
│
├── manifest.json
├── README.md
├── SETUP.md
├── LICENSE
├── .gitignore
└── package.json

Configuration

Manifest.json Overview

Key sections to understand:

{
  "manifest_version": 3,
  "name": "Bookmark Sync",
  "version": "3.0.0",
  
  "permissions": [
    "bookmarks",  // Read/write bookmarks
    "storage",    // Use chrome.storage API
    "alarms",     // Periodic maintenance & debounce
    "tabs"        // Open manager in new tab
  ],
  
  "background": {
    "service_worker": "background.js",
    "type": "module"    // MV3: enables ES module syntax
  },
  
  "action": {
    "default_popup": "popup.html"
  }
}

Adding Icons

Create or download icons in these sizes:

16x16 (toolbar icon)
32x32 (browser action icon)
48x48 (extension management page)
128x128 (Chrome Web Store)

Update manifest.json:

"icons": {
  "16": "icons/icon16.png",
  "32": "icons/icon32.png",
  "48": "icons/icon48.png",
  "128": "icons/icon128.png"
}

Development Workflow

1. Daily Development Cycle

# Pull latest changes
git pull origin main

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ... edit files ...

# Test in browser
# (reload extension in browser)

# Commit changes
git add .
git commit -m "Description of changes"

# Push to your fork
git push origin feature/your-feature-name

2. Hot Reload Setup

Since browser extensions don't have hot reload by default:

Make code changes
Go to chrome://extensions/
Click the reload icon on your extension
Test the changes

Pro tip: Keep the extensions page open in a pinned tab for quick reloading.

3. Debugging

Popup Debugging

Right-click extension icon
Select "Inspect popup"
DevTools opens for popup context

Background Script Debugging

Go to chrome://extensions/
Find your extension
Click "Inspect views: service worker"
DevTools opens for background context

Console Logging

// Add debug logs
console.log('[BookmarkSync] Syncing bookmarks...');
console.error('[BookmarkSync] Error:', error);

Testing

Manual Testing Checklist

Create a file tests/manual-test-checklist.md:

# Manual Testing Checklist

## Installation
- [ ] Extension installs without errors
- [ ] Icon appears in toolbar
- [ ] No console errors on install

## Basic Functionality
- [ ] Popup opens when clicking icon
- [ ] Sync button works
- [ ] Manager opens correctly

## Bookmark Operations
- [ ] Create new bookmark → syncs automatically
- [ ] Delete bookmark → removed from storage
- [ ] Edit bookmark → updates in storage
- [ ] Move bookmark → folder structure maintained

## Storage
- [ ] Data persists after browser restart
- [ ] Storage doesn't exceed limits
- [ ] Old data is cleaned up properly

## UI/UX
- [ ] All buttons are clickable
- [ ] Loading states shown appropriately
- [ ] Error messages are clear
- [ ] Responsive design works

Automated Testing (Future)

To add unit tests later:

# Initialize npm project
npm init -y

# Install testing frameworks
npm install --save-dev jest @testing-library/dom

# Create test file
touch tests/bookmark.test.js

Building for Production

Current Build Process

Since this is a simple extension, no build step is currently needed. To prepare for distribution:

Clean up code
- Remove console.logs (or use conditional logging)
- Remove debug code
- Optimize performance
Update version
```
// In manifest.json
"version": "3.0.0"
```
Test thoroughly
- Run through manual test checklist
- Test on multiple browsers
- Test edge cases

Create release package

# Create a zip file (exclude unnecessary files)
zip -r bookmark-sync-v3.0.0.zip . \
  -x "*.git*" \
  -x "node_modules/*" \
  -x "tests/*" \
  -x "docs/*"

Future Build System

Add a build step with webpack/rollup:

npm install --save-dev webpack webpack-cli

Create webpack.config.js for bundling and minification.

Deployment

Chrome Web Store

Create Developer Account
- Go to Chrome Web Store Developer Dashboard
- Pay one-time $5 registration fee
Prepare Assets
- Screenshots (1280x800 or 640x400)
- Promotional images
- Detailed description
- Privacy policy (if collecting data)
Upload Extension
- Create zip file
- Upload to dashboard
- Fill in listing details
- Submit for review

Firefox Add-ons

Create Account
- Go to Firefox Add-on Developer Hub
Submit Extension
- Upload zip file
- Provide source code (if using minification)
- Fill in listing information
- Submit for review

Troubleshooting

Common Issues

Extension Won't Load

Problem: "Manifest file is missing or unreadable"
Solution: Verify manifest.json syntax with a JSON validator

Background Script Errors

Problem: Background script not running
Solution: Check service worker in chrome://extensions/
        Look for errors in console

Storage Not Persisting

Problem: Data lost on browser restart
Solution: Verify you're using chrome.storage.local, not sessionStorage

Permissions Denied

Problem: Cannot access bookmarks API
Solution: Check manifest.json has "bookmarks" in permissions array

Debug Mode

Add this to your code for enhanced debugging:

const DEBUG = true; // Set to false for production

function debug(...args) {
  if (DEBUG) {
    console.log('[BookmarkSync]', ...args);
  }
}

// Usage
debug('Syncing bookmarks...', bookmarkCount);

Additional Resources

Documentation

Communities

r/browserextensions
Chrome Extension Google Group
Stack Overflow [chrome-extension tag]

Tools

Next Steps

✅ Complete initial setup
📖 Read through the codebase
🐛 Fix any existing issues
✨ Add new features from roadmap
🧪 Write tests
📦 Prepare for distribution

Happy coding! If you encounter any issues not covered here, please open an issue on GitHub.

FilesExpand file tree

SETUP.md

Latest commit

History