Bookshelf

An interactive web-based library to showcase your book collection. To preview what it looks like in production, visit my own bookshelf.

Features

• Three Unique Views:
  • Shelf: A realistic, scrolling bookshelf with physics-based momentum and tilt animations.
  • Stacks: A clean, grid-based list view for efficiency.
  • Coverflow: A coverflow view of your library.
• Dynamic Physics: Smooth scrolling and tilt mechanics that react to your scroll velocity.
• Performance: Lazy loading for covers and DOM elements.
• Search & Filter: Instant fuzzy search and filtering by author, title, or year.
• Auto-Theming: Extracts cover colors to color-code book spines and details.
• Guided Library Management: A CLI for building, adding, editing, removing, and validating books.

Requirements

• Linux is the supported target.
• Node.js 18 or newer.
• Optional: ImageMagick for spine color extraction.

The CLI is plain Node.js and may work on macOS, but macOS is not currently tested or documented as a supported platform. The installer intentionally uses the Linux/XDG-style per-user layout under ~/.local.

Installation

Install the bookshelf command:

curl -fsSL https://raw.githubusercontent.com/aloglu/bookshelf/main/install.sh | bash

The installer creates:

~/.local/bin/bookshelf
~/.local/share/bookshelf/

~/.local/bin/bookshelf is the command you run. ~/.local/share/bookshelf is the single installed bookshelf, including both the local library source and the public site files.

If ~/.local/bin is not in your PATH, add it to your shell profile.

Uninstall:

bookshelf uninstall

Uninstall removes the installed bookshelf directory. Back up ~/.local/share/bookshelf/library first if you want to keep your library data.

Layout

The installed bookshelf uses this structure:

~/.local/share/bookshelf/
  library/
    books.json
    manual-covers/
  public/
    index.html
    css/
    js/
    data/
      books.js
      covers/
    fonts/
    img/

library/books.json is the editable source of truth. public/data/books.js is generated for the frontend.

Migration

To migrate an old backup, copy your old files into the installed bookshelf:

cp old-backup/data/books.json ~/.local/share/bookshelf/library/books.json
mkdir -p ~/.local/share/bookshelf/library/manual-covers
cp -a old-backup/data/manual-covers/. ~/.local/share/bookshelf/library/manual-covers/
mkdir -p ~/.local/share/bookshelf/library/covers
cp -a old-backup/data/covers/. ~/.local/share/bookshelf/library/covers/
bookshelf build

Do not copy old books.js; public/data/books.js is generated by bookshelf build.

If you put old covers in library/covers, bookshelf build moves them into public/data/covers and removes library/covers after it is empty.

Viewing And Publishing

Open the local site:

xdg-open ~/.local/share/bookshelf/public/index.html

To publish the static bookshelf, upload the contents of:

~/.local/share/bookshelf/public/

Do not upload library/; it is local editable source data.

Managing Your Library

Run the interactive manager from anywhere:

bookshelf

The manager asks what you want to do:

• Add a new book
• Modify an existing book
• Remove a book
• Apply manual cover files
• Build or refresh the library
• Validate the library

Direct Commands

The guided workflow is intended for normal use, but direct commands are available for automation:

bookshelf build
bookshelf add
bookshelf update
bookshelf remove
bookshelf covers
bookshelf validate

Examples:

bookshelf add --title "Dune" --author "Frank Herbert" --isbn "9780441172719"
bookshelf build --fetch-covers
bookshelf update --id-or-isbn "9780441172719" --binding "Hardcover"
bookshelf remove --id-or-isbn "9780441172719"
bookshelf covers --id-or-isbn "9780441172719"

Covers

Published covers live in public/data/covers.

To override or add a cover manually, place an image in library/manual-covers using the book ISBN or id as the filename:

~/.local/share/bookshelf/library/manual-covers/9780441172719.jpg

Then apply that one manual cover and regenerate the frontend data:

bookshelf covers --id-or-isbn "9780441172719"

To apply all matching manual covers:

bookshelf covers --all

To fetch missing ISBN covers from Open Library:

bookshelf build --fetch-covers

License

Released under the MIT License.

Acknowledgements

I was inspired by Marius Balaj’s own bookshelf project.