GitHub - raghavan/BookSync: 📚 Privacy-first, self-hosted alternative to Goodreads. Own your reading data.

6 min read Original article ↗

📚 BookSync - Your Privacy-First Personal Goodreads

Own your reading data. No ads. No tracking. No corporate algorithm.

A self-hosted, privacy-focused alternative to Goodreads that puts you in complete control of your reading life.

Next.js TypeScript License Privacy

🎯 Why BookSync?

The Problem with Goodreads

Goodreads has several issues:

  • 📊 Your data is a product - Track, analyze, and monetize your reading habits
  • 🔒 No data export - Limited ability to truly own or migrate your reading history
  • 🕵️ Privacy concerns - Reading preferences reveal personal, political, and professional interests

The BookSync Solution

BookSync is a privacy-first, self-hosted reading tracker that gives you:

  • 🔐 Complete Privacy: Your reading data stays in YOUR Airtable base, encrypted and under your control
  • 🏠 Self-Hosted: Run it locally or deploy it yourself
  • 🎨 Full Customization: Modify the code to fit your exact needs
  • 🤖 Optional AI: Use AI recommendations only if YOU choose to enable them
  • 📱 Modern Interface: Built with modern web technologies for a smooth experience

✨ Features

  • ⚡ Easy Setup - One-click Airtable setup with template CSV (5 minutes to get started)
  • 🔍 Smart Book Search - Search millions of books via Google Books API
  • 📖 Reading Progress Tracking - Mark books as "To Read", "Reading", or "Finished"
  • ⭐ Personal Ratings & Reviews - Rate books and save your thoughts and takeaways
  • 🎨 Beautiful, Clean UI - Modern interface that's actually pleasant to use
  • 💾 Airtable Backend - All your data in your own Airtable base (free tier: 1,200 records)
  • 🤖 AI Recommendations - Optional OpenAI integration for personalized book suggestions
  • 📊 Full Data Control - Export, backup, or analyze your data however you want
  • 🔒 Privacy by Design - No telemetry, no tracking, no third-party scripts

🚀 Quick Start

Prerequisites

  • Node.js 18+ installed
  • An Airtable account (free tier works great)
  • Optional: Google Books API key (for better search results)
  • Optional: OpenAI API key (for AI recommendations)

1. Clone the Repository

git clone https://github.com/yourusername/booksync.git
cd booksync
npm install

2. Set Up Your Airtable Base

Option A: Easy Setup with Template CSV (Recommended ⚡)

  1. Create a new Airtable base at airtable.com
  2. Delete the default table (or rename it)
  3. Import the template CSV:
    • Download airtable-template.csv from this repo
    • In Airtable, click "Add or import" → "CSV file"
    • Upload the template CSV
    • Airtable will automatically create all the fields with the correct types!
  4. Configure the "Status" field:
    • Click on the "Status" column header
    • Select "Customize field type" → "Single select"
    • The options (To Read, Reading, Read) should already be there from the template
  5. Delete the sample rows from the template (keep the empty table structure)

That's it! Your table is now set up with all the correct fields.

Option B: Manual Setup (Alternative)

If you prefer to set up the table manually:

Click to expand manual setup instructions
  1. Create a new Airtable base at airtable.com
  2. Create a table called "Books" with these fields:
Field Name Field Type Notes
Book Name Single line text Primary field (required)
ISBN Single line text
Status Single select Options: "To Read", "Reading", "Read"
Cover Attachment Book cover image
Author Single line text
Categories Single line text
Subtitle Single line text
Book Title Single line text
Started Date When you started reading
Finished Date When you finished
Rating Number Your rating (1-5)
Review & Takeaways Long text Your notes and thoughts
Year of Read Number Year completed

Get Your Airtable Credentials (Required for both options)

  • API Key: Go to airtable.com/create/tokens

    • Click "Create new token"
    • Give it a name (e.g., "BookSync")
    • Add these scopes: data.records:read, data.records:write
    • Add access to your Books base
    • Click "Create token" and copy it (starts with pat_...)

  • Base ID:

    • Open your Airtable base
    • Click "Help" (?) in the top-right
    • Select "API documentation"
    • Your Base ID is shown at the top (starts with app_...)

3. Get Your Google Books API Key (Optional but Recommended)

Why you need this: The Google Books API provides rich book metadata (covers, descriptions, ISBNs). Without it, search functionality is limited.

Steps:

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Books API:
    • Click "Enable APIs and Services"
    • Search for "Books API"
    • Click "Enable"
  4. Create credentials:
    • Go to "Credentials" in the left sidebar
    • Click "Create Credentials" → "API Key"
    • Copy your API key

Note: Google Books API has a free tier with generous limits (1,000 requests/day). More than enough for personal use.

4. Get Your OpenAI API Key (Optional)

Why you need this: Enables AI-powered book recommendations based on your reading history. This is completely optional - the app works fine without it.

Steps:

  1. Go to platform.openai.com
  2. Sign up or log in
  3. Go to "API Keys" in your account settings
  4. Click "Create new secret key"
  5. Give it a name (e.g., "BookSync Recommendations")
  6. Copy the key (starts with sk-...)
  7. Set up billing: OpenAI requires a payment method, but costs are minimal
    • Recommendations use GPT-4 or GPT-3.5-turbo
    • Average cost: ~$0.01-0.05 per recommendation
    • Set a monthly budget limit in your OpenAI account for safety

Privacy Note: When you use AI recommendations, your book titles are sent to OpenAI's API. This is optional and disabled by default.

5. Configure Environment Variables

Create a .env.local file in the root directory:

# Airtable Configuration (REQUIRED)
AIRTABLE_API_KEY=pat_your_api_key_here
AIRTABLE_BASE_ID=app_your_base_id_here
AIRTABLE_TABLE_NAME=Books

# Google Books API (OPTIONAL but recommended for better search)
GOOGLE_BOOKS_API_KEY=your_google_books_api_key_here

# OpenAI API (OPTIONAL - only needed for AI recommendations)
OPENAI_API_KEY=sk_your_openai_api_key_here

6. Run the Application

# Development mode
npm run dev

# Production mode
npm run build
npm start

Open http://localhost:3000 in your browser.

What Data Goes Where?

Data Where it goes Why
Book searches Google Books API To find book metadata (titles, covers, ISBNs)
Your saved books Your Airtable base Storage you control
AI recommendations OpenAI API (optional) Only if you enable this feature
Analytics Nowhere We don't collect any usage data

Self-Hosting Options

  • Vercel (free tier available) - Easiest option

📖 Usage

  1. Search for books - Use the search bar to find any book
  2. Add to your library - Click to save books to your Airtable
  3. Track progress - Mark books as "To Read", "Reading", or "Finished"
  4. Add notes - Rate books and save your thoughts and takeaways
  5. Get recommendations - (Optional) Use AI to discover similar books
  6. View your collection - See all your books in a beautiful grid view

🛠️ Customization

BookSync is designed to be easily customizable:

  • Modify the Airtable schema - Add custom fields for genres, publishers, purchase date, etc.
  • Change the UI - Edit the React components to match your style
  • Add features - Want reading statistics? A reading challenge tracker? Build it!
  • Export your data - Airtable allows CSV/JSON export anytime

🤝 Contributing

This project is open source because reading is personal, and personal data should be in your control.

Contributions are welcome!

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

TL;DR: You can use, modify, and distribute this freely. Do whatever you want with it.

Built with ❤️ for people who love reading and value privacy.

Your reading journey is personal. Keep it that way.