Skip to content

Epic: 'Build your library' Experience on My Books Page #13255

Open
1 of 2 issues completed
Open

Description

@Sadashii

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.

Image

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
Loading

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/import template.
  • 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.

Activity

  1. added
    Needs: TriageThis issue needs triage. The team needs to decide who should own it, what to do, by when. [managed]
    Needs: Staff DecisionIssues that are blocked on a staff member's decision
    Affects: UIIssues with the web site's user interface. [managed]
    Module: JavaScriptIssues related to the JavaScript functionality. [managed]
    Affects: ServerIssues with the server (olweb) or its plugins. [managed]
    Affects: DataIssues that affect book/author metadata or user/account data. [managed]
    on Aug 4, 2026
  2. openlibrary-bot commented on Aug 4, 2026

    @openlibrary-bot
    Collaborator

    Thank you @Sadashii for submitting this issue!

    ⚠️ Contributors, this issue will be ready to work on once:

    • Triage — maintainers will add Priority: * and Lead: @*
    • Needs: Designs — UI/UX direction required before implementation
    • Needs: Staff Decision — how this Epic relates to the existing, already-staffed retention/onboarding epics (see Context below) needs a maintainer call before sub-PRs are opened

    Context

    • The three sub-features already have existing infrastructure — this is a revamp, not greenfield work in most cases:
      • /account/import and /account/export are already separate routes/classes (import_books and export_books), just sharing one template today:
        class import_books(delegate.page):
        path = "/account/import"
        @require_login
        def GET(self):
        user = accounts.get_current_user()
        username = user["key"].split("/")[-1]
        template = render["account/import"]()
        return MyBooksTemplate(username, "imports").render(header_title=_("Imports and Exports"), template=template)
        class fetch_goodreads(delegate.page):
        and
        class export_books(delegate.page):
        path = "/account/export"
        @require_login
        def GET(self):
        i = web.input(type="")
        export = self.get_export(i.type)
        data = export.make_export(export.get_data(), export.fieldnames)
        web.header("Content-Type", "text/csv")
        web.header("Content-disposition", f"attachment; filename={export.filename}")
        return delegate.RawText(data, content_type="text/csv")
        def get_export(self, export_type: str) -> PatronExport:
        export: PatronExport | None = None
        match export_type:
        case "reading_log":
        export = ReadingLogExport()
        case "book_notes":
        export = BookNoteExport()
        case "reviews":
        export = ReviewExport()
        case "lists":
        export = ListExport()
        case "ratings":
        export = RatingExport()
        case _:
        raise KeyError("Unrecognized export type")
        return export
      • The barcode scanner already exists as a Vue component (openlibrary/components/BarcodeScanner.vue, .../BarcodeScanner/components/LazyBookCard.vue) and currently redirects on the first detected barcode rather than scanning continuously:
        location.href = this.returnTo.replace('$$$', isbn);
        — LazyBookCard.vue has no shelf/dropdown UI yet, so that part of Sub-PR 3 is genuinely net-new.
      • mybooks_home already computes shelf counts for the current user, which is the data an empty-state check would key off of:
        return render["account/mybooks"](
        mb.user,
        docs,
        key=mb.key,
        public=mb.is_public,
        owners_page=mb.is_my_page,
        counts=mb.counts,
        lists=mb.lists,
        component_times=mb.component_times,
        )
      • /explore already exists as the Library Explorer route (library_explorer in openlibrary/plugins/upstream/code.py), reusing the LibraryExplorer Vue component tree. Sub-PR 1's proposed /books/explore genre-browsing grid would sit adjacent to this and should clarify how it differs.
    • Overlapping open work, same author: PR Feat/improvements to goodreads import feature #12276 ("Feat/improvements to goodreads import feature"), opened by @Sadashii and currently assigned to @jimchamp, already overhauls the Goodreads import into a server-side handler (/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.
    • Overlapping existing epics (all currently open, staff-led):

    Issue Assessment

    Open questions

    • Should this Epic be tracked as a sub-issue/child of My Books #13245 ("Improve Retention") rather than a standalone parallel epic, given the overlapping scope?
    • How should Sub-PR 2 (Goodreads revamp) relate to the author's own open PR Feat/improvements to goodreads import feature #12276, which already implements a server-side Goodreads import overhaul against /account/import?
    • Should Sub-PR 1's genre-browsing grid be coordinated with, or built on top of, the in-progress Genre Explorer design work in Epic: Browse the Stacks: a discovery/explore-centric homepage #13158, instead of a separate implementation?
    • The mockup images are hosted on 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

    • Attach the mockup images directly to the issue (drag-and-drop upload) rather than linking to a personal fork branch, so they don't disappear if the branch is removed.
    • Add measurable baseline data or targets for the stated retention/engagement claims (e.g., current empty-shelf rate among new signups, current import funnel drop-off) — the motivation section asserts impact ("increase significantly") without citing numbers.
    • Clarify success/testing criteria for the Epic as a whole (the individual PR "Deliverables" are described, but there's no stated way to verify the onboarding banner actually improves retention post-launch).

    🔔 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
    • Triage — correct labels applied or removed
    • Problem / opportunity — problem is clear (empty onboarding experience hurts retention), audience identified (new patrons), actionable
    • Scope — issue bundles 5 separate PRs (import/export split, explorer page, barcode scanner, Goodreads revamp, banner) into one Epic; scope itself is reasonable for an Epic, but overlaps with 3 other open epics that already cover parts of it
    • Justification — motivation is well-argued qualitatively but has no measurable baseline/impact figures
    • Success & testing criteria — individual PR deliverables are described; no explicit criteria for validating the retention hypothesis after launch
    • Proposal & breakdown — concrete, detailed plan present, including an incremental/production-mergeable PR split; more thorough than most issue breakdowns
    • If bug: environment & repro steps — n/a, this is a feature epic, not a bug
    • Risks, concerns, open questions — surfaced above (overlap with existing epics/PRs)
    • Richy context — relevant code, commits, PRs reviewed; overlapping work identified (see Context)
    • References — mockups exist but are linked from a personal fork branch rather than attached to the issue

    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.

  3. lokesh commented on Aug 4, 2026

    @lokesh
    Collaborator

    UI feedback:

    1. Additional import sources — have you considered StoryGraph and LibraryThing? Both export CSV, so it's a column-mapping layer, not a new pipeline. But the current code is Goodreads-schema-shaped throughout: process_goodreads_csv keys off ISBN/ISBN13/Book Id (account.py:1387), and the results table hardcodes My Rating/Exclusive Shelf/Date Read (import.html:91). PR 4 is the moment to decide — a wizard built against a normalized record makes new sources a mapping table; one built Goodreads-shaped means reopening the whole flow later.
    2. Put the search input in the banner itself. All three cards currently navigate away, and PR 2's search bar lives on a separate explorer page — so a patron's first book is always a page load away. A large search input inline in the banner lets them start adding on arrival. Keep the Goodreads card beside it. This also un-gates the banner from the explorer page, making PR 2 an enhancement rather than a blocker.
    3. Is the barcode scanner earning one of three slots? I'd want usage numbers first — and we can't get them today: the nav entry point (nav_head.html:112) has no data-ol-link-track, so there's no link event, only /barcodescanner pageviews. It's also touch-only, which is an odd fit for a desktop-first onboarding surface. Adding tracking is cheap and would let us decide with data.
    4. Homepage placement — should the import card surface there too, where more patrons will see it? If so it needs dismissal, which we have no pattern for today, plus a persistence decision (per-account vs. localStorage). I'd lean per-account, but that's its own scope, not a PR 5 add-on.
  4. Sadashii commented on Aug 5, 2026

    @Sadashii
    CollaboratorAuthor

    Thanks for taking out the tme and your feedback.

    1. Good point. We have been discussing adding those two sources, currently though, to focus on the perspective, I understand having that as a later-on flow-enhancement issue later on.
    2. That makes sense, would it be possible for you to share a quick wireframe or so about how the banner should then be structured, I'm unable to visualize that with the incorportated books explorer section.
      For the books explore section, I'm considering a tab based layout instead of carousels to improve discovery.
    Image
    1. Since the barcode scanner is only accessible from that one source (and unlikely to be shared as the url) - perhaps that can be a good indicator of usage.
    2. That makes sense - will keep this question open for further discussion down the road. Unsure as of now, agreed on the per-account option, that makes sense.
  5. added
    Type: EpicA feature or refactor that is big enough to require subissues. [managed]
    on Aug 5, 2026
  6. mekarpeles commented on Aug 5, 2026

    @mekarpeles
    Member

    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:

    1. Some experience for easily searching for [one or more] book(s) [to add]
    2. To ensure the barcode scanner opens in a mode that lets the patron lookups n books and then add them to a reading log shelf (I don't recall if this functionality is live).
    3. Reconcile the goodreads import flow (and possibly extend to other platforms in the future).
    • One thing we could do as a follow-up is have a buttons for "Request [Storygraph, LibraryThing, ISBN] Integration" and understand what the demand looks like for each platform (or if there's some other import option patrons identify as important to them.

    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.

  7. added
    Lead: @mekarpelesIssues overseen by Mek (Staff: Program Lead) [managed]
    Priority: 2Important, as time permits. [managed]
    and removed
    Needs: TriageThis issue needs triage. The team needs to decide who should own it, what to do, by when. [managed]
    Needs: ResponseIssues which require feedback from lead
    on Aug 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Affects: DataIssues that affect book/author metadata or user/account data. [managed]Affects: ServerIssues with the server (olweb) or its plugins. [managed]Affects: UIIssues with the web site's user interface. [managed]Lead: @mekarpelesIssues overseen by Mek (Staff: Program Lead) [managed]Module: CSSModule: JavaScriptIssues related to the JavaScript functionality. [managed]Needs: DesignsNeeds: Staff DecisionIssues that are blocked on a staff member's decisionPriority: 2Important, as time permits. [managed]Type: EpicA feature or refactor that is big enough to require subissues. [managed]

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

    ⌂ Proxy