tijs.org / storygraph-to-goodreads
Migrate your reading data between Storygraph and Goodreads. Makes it possible to import from Storygraph in to bookhive.buzz
fork atom
TypeScript 80.0%
CSS 9.6%
HTML 0.4%
Other 10.0%
4 1 0

Clone this repository

https://tangled.org/tijs.org/storygraph-to-goodreads
git@tangled.org:tijs.org/storygraph-to-goodreads

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

Storygraph ↔ Goodreads CSV Converter#

A simple web service hosted on Val Town that converts reading data between Storygraph and Goodreads CSV formats.

Features#

  • Bidirectional conversion: Convert from Storygraph to Goodreads format and vice versa
  • Smart field mapping: Automatically maps compatible fields between formats
  • Goodreads enrichment: Automatically enriches book data with complete titles and author information from Goodreads API
  • ISBN handling: Parses and converts between ISBN-10 and ISBN-13 formats
  • Date format conversion: Handles different date formats between platforms
  • Format mapping: Converts book formats (digital ↔ Kindle Edition, etc.)
  • Rate limiting: Respectful API usage with built-in rate limiting for Goodreads requests
  • Temporary storage: Files are stored temporarily and auto-deleted after 24 hours
  • Progress tracking: Real-time upload and conversion progress with detailed status updates
  • Clean UI: Simple drag-and-drop interface with format selection

How to Use#

  1. Choose conversion direction: Select whether you're converting from Storygraph to Goodreads or vice versa
  2. Upload your CSV: Drop your export file or click to browse and select it
  3. Download converted file: Once processing is complete, download your converted CSV file
  4. Import to target platform: Use the downloaded file to import your reading data

Field Mapping#

Storygraph → Goodreads#

  • Direct mappings: Title, Authors, Star Rating, Review, Read Status, Read Count, Date Added, Last Date Read
  • Smart conversions:
    • Sequential Book IDs (1, 2, 3...)
    • ISBN/UID → separate ISBN and ISBN13 fields
    • Format → Binding (digital → Kindle Edition, etc.)
    • Authors + Contributors → Author + Additional Authors
  • Goodreads enrichment: Automatically looks up books on Goodreads to get complete titles and normalized author names
  • Empty fields: Publisher, Number of Pages, Year Published, Average Rating (not available in Storygraph)

Goodreads → Storygraph#

  • Direct mappings: Title, Star Rating, Review, Read Status, Read Count, Date Added, Date Read
  • Smart conversions:
    • Author + Additional Authors → Authors field
    • ISBN13/ISBN → ISBN/UID field
    • Binding → Format (Kindle Edition → digital, etc.)
  • Empty fields: Moods, Pace, Character Development fields, Content Warnings (not available in Goodreads)

Technical Details#

Architecture#

  • Backend: Hono framework with TypeScript
  • Frontend: React with TypeScript
  • Storage: Val Town blob storage (temporary, 24-hour cleanup)
  • Deployment: Val Town platform

File Structure#

storygraph-to-goodreads/
├── backend/
│   ├── index.ts           # Main Hono server
│   └── utils/
│       ├── converter.ts   # CSV conversion logic
│       └── goodreads-enricher.ts  # Goodreads API integration
├── frontend/
│   ├── index.html         # Bootstrap HTML
│   ├── index.tsx          # React app entry
│   ├── components/
│   │   └── App.tsx        # Main app component
│   └── style.css          # Styles
├── shared/
│   └── types.ts           # Shared TypeScript types
├── cleanup-cron.ts        # Cron job for blob cleanup
└── deno.json              # Deno configuration

API Endpoints#

  • POST /api/convert - Upload and convert CSV file
  • GET /api/download/:key - Download converted file
  • GET /api/status/:key - Check conversion status
  • GET /api/health - Health check

Privacy & Data Handling#

  • No permanent storage: All files are temporarily stored and automatically deleted after 24 hours
  • No tracking: No user data is collected or tracked
  • Minimal external calls: Only makes API calls to Goodreads for book enrichment (optional feature)
  • Rate limited: Respectful API usage with built-in delays between requests
  • Secure: Files are stored with random keys and cleaned up automatically

Development#

Prerequisites#

  • Deno runtime
  • Val Town account

Commands#

deno task check    # Type check
deno task fmt      # Format code
deno task lint     # Lint code
deno task test     # Run tests
deno task quality  # Run all quality checks + tests
deno task deploy   # Deploy to Val Town

Testing#

The conversion logic includes comprehensive tests for:

  • ISBN parsing and conversion
  • Date format handling
  • Field mapping accuracy
  • Bidirectional conversion integrity
  • Goodreads API integration and enrichment
  • Rate limiting functionality

Limitations#

  • CSV files only (no other formats supported)
  • Some platform-specific fields cannot be converted (e.g., Goodreads ratings → Storygraph moods)
  • File size limited by Val Town blob storage limits
  • Temporary storage only (24-hour retention)

Contributing#

This project is built for Val Town deployment. To contribute:

  1. Fork the repository
  2. Make your changes
  3. Test with deno task quality
  4. Submit a pull request

License#

MIT License - feel free to use and modify as needed.