Skip to content

8. Blueprints

Jump to bottom
Jimmy Pautz edited this page Sep 26, 2026 · 3 revisions

Storefront Blueprints

Storefront Blueprints (.blueprint) allow you to snapshot, export, share, and replicate your entire KOReader customization setup—including installed plugins, user patches, e-reader fonts, screensavers, and Storefront configuration—in a single portable file or a short 6-character cloud code.

Whether setting up a new e-reader, backing up your configuration, or sharing a curated reading environment with friends or the community, Blueprints automate the entire discovery and installation process.

Accessing Blueprints

You can access the Blueprints system through multiple convenient entry points:

  1. Storefront Settings: Tap the Gear icon (⚙️) → select Blueprints ›.
  2. Installed Tab Toolbar: Tap the [ Blueprint ] button located at the top of the Installed tab.
  3. KOReader File Manager: Tap any .blueprint file directly within KOReader's file browser to inspect and apply it.
  4. Gesture / Dispatcher Shortcut: Assign the storefront_blueprints action to any tap, swipe, or multiswipe gesture via KOReader's Gesture Manager.

Creating & Exporting a Blueprint

Exporting packages your chosen items into a clean, human-readable .blueprint JSON file.

  1. Open the Blueprints menu and tap Export Blueprint.
  2. Customize your export settings:
    • Version Strategy:
      • Latest Releases (Recommended): Stores repository references. When imported, Storefront fetches the freshest compatible release for each component.
      • Pin Current Installed Versions: Freezes exact release tags and Git commit SHAs for 100% reproducible environments.
    • Component Checkboxes: Selectively include or exclude:
      • ☑ Plugins — Installed community plugins.
      • ☑ Patches — Installed user patches (.lua).
      • ☑ Fonts — Installed e-reader font families.
      • ☑ Screensavers — Downloaded sleep wallpapers.
      • ☑ Settings — Storefront configuration options.
  3. Choose your export destination:
    • Save to Storage: Writes the file to koreader/blueprints/<name>.blueprint. If a file with that name already exists, Storefront automatically appends a timestamp to preserve previous exports.
    • Share Online: Uploads the blueprint and generates a 6-character cloud code.

Cloud Sharing (Shortcodes)

Storefront includes cloud synchronization powered by Cloudflare Workers:

  • Short 6-Character Codes: Share setups using compact alphanumeric codes (e.g., A8K2M9) that are quick to type on an e-ink on-screen keyboard.
  • Kindle & E-Reader Friendly: Uses pure outbound HTTPS requests. No local listening ports, no firewall issues, and no GitHub Personal Access Tokens (PAT) required.
  • Flexible Input: The code entry dialog is case-insensitive and automatically strips dashes, spaces, #, and SF- prefixes.

Importing & Applying a Blueprint

When importing a blueprint (either from local storage or via a cloud code), Storefront never blindly overwrites your device:

  1. Diff & Review: Storefront analyzes the blueprint against your device's current inventory and displays a categorized summary:
    • [NEW]: Items in the blueprint that are not installed on your device (selected by default).
    • [UPDATE]: Items where the blueprint specifies a newer version than what you currently have installed.
    • [INSTALLED]: Items you already possess (unchecked by default).
  2. Selective Installation: Use the checkboxes to cherry-pick exactly what you want to install or skip.
  3. E-Ink Navigation: The multi-page diff dialog fully supports physical hardware page-turn buttons (PageDown/PageUp, forward/back buttons) and touch swipes.
  4. Batch Installer: Tap Apply Selected. Storefront sequentially downloads and installs each plugin, patch, and font, showing real-time progress.
  5. Clean Restart: Once installation finishes, Storefront prompts to restart KOReader with a single tap to activate all new components cleanly.

Blueprint Specification & Schema

Storefront Blueprints conform to the official JSON Schema:

  • Schema URL: https://ultimatejimmy.github.io/storefront.koplugin/schema/v1.blueprint.json
  • Format Version: 1
  • Generator: Storefront

Power users can create, edit, or host .blueprint files on GitHub or personal websites.

Clone this wiki locally