Repository navigation
Description
Epic: "Build your library" Experience on My Books Page
Summary
A new patron's first visit to My Books is a blank slate — the empty-room equivalent of walking into a library with no books. We know populated shelves drive engagement and retention, but right now we actively work against that: import is buried, and most patrons never learn the feature exists at signup. This Epic replaces the empty state with an encouraging "Build your library" onboarding banner at the top of My Books, linking out to three low-friction cataloging workflows built or revamped as part of this work.
This is a planning/implementation issue, not a single PR — it's split below into five independently mergeable PRs so nothing ships as a broken or empty placeholder page. Close this issue once all five PRs below are merged and the banner is live on My Books.
graph TD
PR1[PR 1: Import/Export UI Splitting] --> PR4[PR 4: Goodreads Match Resolution]
PR2[PR 2: Find Your First Book Explorer] --> PR5[PR 5: Build Your Library Banner & Integration]
PR3[PR 3: Mass Barcode Scanner Upgrade] --> PR5
PR4 --> PR5
Checklist
1. Import/Export UI Splitting (self-contained refactor) — separates the tangled /account/import and /account/export routes/menus into dedicated screens. Low risk: export keeps working exactly as it does today, import gets its own view and controller, and no Goodreads CSV parsing logic changes yet. This is the foundation PR 4 builds on.
- Create a page dedicated solely to Importing (Goodreads, etc.).
- Create a separate page/tab dedicated to Exporting data (reading logs, notes, reviews, lists, ratings).
- Target files:
openlibrary/templates/account/import.html(import-only),openlibrary/templates/account/export.html[NEW],openlibrary/plugins/upstream/account.py(split route handlers).
2. "Find your first book" Explorer Page — a standalone discovery entry point patrons can reach directly (link, search suggestion) independent of the onboarding banner, so it can ship and be useful on its own before PR 5 wires it in.
- Browse-by-genre grid of book covers, in the style of standard library explorers.
- Mass-add UI: book cards carry a prominent "Add to bookshelf" dropdown/button directly on the card, no redirect to the book details page required.
- Central, prominent search bar built on the new search autocomplete component, optimized for rapid multi-book adds.
- Target files:
openlibrary/templates/my_books/explore.html[NEW],openlibrary/plugins/upstream/mybooks.py(new controller/routes),openlibrary/plugins/openlibrary/js/my-books/(new explorer components).
3. Mass Barcode Scanner Upgrade (self-contained) — the /barcodescanner camera view already exists in beta; this upgrades it to continuous scanning instead of redirecting after a single detection, an isolated frontend change.
- Interaction loop: scan barcode → a lazy card pops up under the viewport with confirmation/status (e.g. "Added to Want to Read" or "ISBN Unavailable") → camera stays active → patron scans the next barcode.
- Embed shelf/bookshelf-dropper buttons directly inside each scanned card so patrons can scan, add, and keep scanning without leaving the view.
- Target files:
openlibrary/components/BarcodeScanner.vue(continuous scan loop + inline feedback),openlibrary/components/BarcodeScanner/components/LazyBookCard.vue(embedded shelf buttons).
4. Revamped Goodreads Match Resolution Flow — builds directly on the clean /account/import template from PR 1, so it's gated on that merging first.
- Wizard interface following the latest Goodreads import mockups.
- Interactive resolution screen handling common edge cases gracefully: books not found in Solr, edition mismatches, custom matching configuration.
- Let patrons preview and customize target shelves (want-to-read, already-read, etc.) before running the import.
- Target files:
openlibrary/templates/account/import.html, import parser + resolution-table logic (new).
5. "Build your library" Landing Banner & Integration (Major PR — merges only after PRs 1–4 are stable in production) — ties the three onboarding channels together on My Books.
- Empty-state detection: patron's shelves (want-to-read, currently-reading, already-read, stopped-reading) are all at 0 books.
- Banner renders on both desktop and mobile with a milestone progress bar (e.g.
0 / 20 books, step-dot style) motivating patrons toward unlocking personalized recommendations. - Three action cards inside the banner: Search your first book (→ Explorer, PR 2), Import Goodreads library (→ split import + resolution flow, PRs 1/4), Scan barcodes (ISBN) (→ mass scanner, PR 3).
- Target files:
openlibrary/templates/account/mybooks.html(shelf-count check + conditional rendering),openlibrary/plugins/upstream/mybooks.py(backend checks/metrics for empty accounts),static/css/components/library-builder.css[NEW].
Next steps
- PR 1 (Import/Export split), PR 2 (Explorer), and PR 3 (Barcode scanner) have no dependencies on each other and can be worked in parallel.
- PR 4 (Goodreads match resolution) is gated on PR 1 merging first — it builds on the split
/account/importtemplate. - PR 5 is gated on PRs 1–4 all being stable in production, so all three onboarding channels ("Explore", "Import", "Scan") work flawlessly before they're surfaced together in the banner.
- Close this issue once PR 5 is merged and the banner is confirmed live with milestone tracking working end to end.
Engineering Standards
- Python: double quotes, max line length 162, Ruff-compliant import order.
- JS: ESLint-compliant, single quotes, no jQuery in new components.
- CSS: Stylelint-compliant — no hex colors, use variables defined in
static/css/. - i18n: don't split sentences into separate translatable fragments around HTML links. Use single translatable strings with placeholders (e.g.
%(link_start)s/%(link_end)s) so translators can reposition links per target-language grammar.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
openlibrary-bot commentedon Aug 4, 2026
Thank you @Sadashii for submitting this issue!
Priority: *andLead: @*Context
/account/importand/account/exportare already separate routes/classes (import_booksandexport_books), just sharing one template today:openlibrary/openlibrary/plugins/upstream/account.py
Lines 832 to 843 in acd2b35
openlibrary/openlibrary/plugins/upstream/account.py
Lines 1122 to 1153 in acd2b35
openlibrary/components/BarcodeScanner.vue,.../BarcodeScanner/components/LazyBookCard.vue) and currently redirects on the first detected barcode rather than scanning continuously:openlibrary/openlibrary/components/BarcodeScanner.vue
Line 227 in acd2b35
LazyBookCard.vuehas no shelf/dropdown UI yet, so that part of Sub-PR 3 is genuinely net-new.mybooks_homealready computes shelfcountsfor the current user, which is the data an empty-state check would key off of:openlibrary/openlibrary/plugins/upstream/mybooks.py
Lines 106 to 115 in acd2b35
/explorealready exists as the Library Explorer route (library_explorerinopenlibrary/plugins/upstream/code.py), reusing theLibraryExplorerVue component tree. Sub-PR 1's proposed/books/exploregenre-browsing grid would sit adjacent to this and should clarify how it differs./account/import/process/goodreads), including custom-shelf list creation and rating/date-read import — this covers much of what Sub-PR 2 describes here. Worth reconciling rather than starting a second, parallel Goodreads rewrite.Theme: Onboarding/Metric: Retention.Needs: DesignsandNeeds: Staff Decision.Issue Assessment
Open questions
/account/import?raw.githubusercontent.com/Sadashii/openlibrary/epic-build-your-library-assets/...(a personal fork branch) rather than attached to the issue — what happens to these links if that branch is ever deleted or rebased?Action items
🔔 Stakeholders
@jimchamp — bookshelf/psql database and JS & partials are your listed areas, and you're already the assigned reviewer on the overlapping Goodreads import PR (#12276) referenced above.
Full triage checklist
Note
This comment was automatically generated by Richy, Open Library's issue enrichment assistant, on behalf of @mekarpeles. This is NOT a sign-off. This issue needs lead review before work begins.
lokesh commentedon Aug 4, 2026
UI feedback:
Sadashii commentedon Aug 5, 2026
Thanks for taking out the tme and your feedback.
For the books explore section, I'm considering a tab based layout instead of carousels to improve discovery.
mekarpeles commentedon Aug 5, 2026
If I understand, the desired end goal is: a section on the My Books page to Build your library
At this stage, I want to be careful that we don't promise a feature we don't have (e.g. unlocking book recommendations -- even if this is something we can do in the future).
In order to create the Build your library section... We need:
nbooks and then add them to a reading log shelf (I don't recall if this functionality is live).Having some sort of prototype / UI of what happens when one clicks any of the three options would be useful. All 3 experiences would likely benefit from dedicated issues that track what needs to happen in that flow/channel.
In terms of development, I would probably also develop each channel independently (ensure the underlying feature is capable of achieving the end state before adding it to the my books page. e.g. there's a world in which the only option we offer is "goodreads" and then continue to add the we decide the other 2 as the experiences are sufficient.