Nano Cart

The problem Nano Cart solves

Many small client sites need to sell a fixed catalogue of 20 to 50 products: a potter, a print-maker, a jewellery designer, an author, a consultant, a gallery. Setting them up with Shopify is overkill (a hosted platform with monthly fees for 30 fixed-price items), and WooCommerce drags in WordPress + MySQL + ongoing plugin patching that the static-site brief was specifically built to avoid. Nano Cart exists for that exact gap. The host site stays static; Nano Cart slots a small product catalogue into it that links each item out to a Stripe Payment Link, PayPal hosted checkout, Square, Gumroad, Ko-fi, or any processor-hosted URL. It is deliberately not a general-purpose e-commerce platform: no variants, no quantity selectors, no multi-item cart, no inventory. It does one thing - serve a small fixed catalogue with strong SEO output and one-click external checkout - and tries to do it well in around 5,750 lines of hand-written code.

Architecture in one diagram

The whole system in three layers - what stays on the client server permanently, what only exists during editing, and what sits above the webroot.

+-----------------------------------------------------------------+
|                     CLIENT SITE (permanent)                     |
|                                                                 |
|  /public_html/shop/                                             |
|    |-- products/      <-- JSON files (the "database")            |
|    |-- categories/    <-- JSON files                            |
|    |-- media/         <-- uploaded images + variants            |
|    |-- assets/        <-- nano-cart.css, nano-cart.js           |
|    |-- core.php       <-- parser, renderer, helpers             |
|    |-- index.php      <-- shop homepage                         |
|    |-- category.php   <-- category page                         |
|    |-- product.php    <-- product page                          |
|    |-- template.php   <-- per-site HTML wrapper                 |
|    |-- bootstrap.php  <-- per-site config paths                 |
|    |-- licence.php    <-- Ed25519 footer verification           |
|    +-- sitemap.xml    <-- regenerated on save                   |
|                                                                 |
|  /shop-config/         <-- OUTSIDE webroot                      |
|    |-- config.json     <-- password hash, licence, settings     |
|    +-- rate-limit.json <-- login attempt tracking               |
+-----------------------------------------------------------------+

+-----------------------------------------------------------------+
|              UNIVERSAL PORTABLE ADMIN (ephemeral)               |
|                                                                 |
|  Uploaded to /public_html/shop/admin/ when editing.             |
|  Removed afterwards. Identical for every deployment.            |
|  Contains zero site-specific data.                              |
+-----------------------------------------------------------------+

Who Nano Cart is for

Nano Cart is built for web developers and agencies who maintain static sites for clients and need to sell a small, fixed catalogue without taking on a database, a CMS, or a hosted platform. Suitable shops: a potter selling 30 hand-thrown pieces through Stripe Payment Links, a jewellery designer with 50 one-off pieces and PayPal checkout, an author selling signed editions and merch with Gumroad, a consultant offering fixed-price service packages with Calendly enquiry, a gallery cataloguing artworks for sale with a contact-form enquiry action. The tool assumes operators are fluent with SFTP - it is not aimed at non-technical end users. For a non-technical shop owner who needs a hosted dashboard, full variants, and inventory tracking, Shopify is the right answer.

Not for you if you sell variant-heavy retail (clothing in sizes/colours, use Shopify), need a catalogue over ~150 SKUs (use WooCommerce), want a multi-item shopping cart (use Big Cartel or Gumroad), or sell subscriptions (use Lemon Squeezy). Nano Cart's smallness is the product.

Why not Shopify, WooCommerce, or Big Cartel?

All three are excellent for shops that need them. Shopify is a full hosted e-commerce platform with monthly fees, ideal for variant-heavy retail; for 30 fixed-price items it is overkill. WooCommerce requires WordPress + MySQL + ongoing plugin patching, which is exactly what the static-site brief was built to avoid. Big Cartel is a hosted option closer in spirit (small shops, no variants) but it's a subscription with limits on item count and your shop lives on their domain. Nano Cart deliberately stays smaller than all of them, runs in the operator's own webroot at /shop/, and uses external checkout links so the visitor never has to trust a multi-tenant cart. When the admin is removed, only flat JSON files and images remain on the server.

Side-by-side

What a product looks like on disk

One product = one JSON file. The sku field is the URL slug. checkout_url points to wherever you want the buy button to send the visitor.

/products/pot-001.json
{
    "sku": "pot-001",
    "title": "Hand-thrown stoneware mug",
    "short_description": "Deep cobalt glaze on natural stoneware, 350ml.",
    "long_description": "Each mug is thrown on the wheel...",
    "category": "pottery",
    "price_display": "£32.00",
    "checkout_url": "https://buy.stripe.com/abc123",
    "images": [
        { "file": "main",  "alt": "Mug, side view",  "is_primary": true },
        { "file": "alt-1", "alt": "Mug, top view",   "is_primary": false }
    ],
    "featured": true,
    "hero_featured": true,
    "image_width": "500",
    "image_height": "auto",
    "image_fit": "contain",
    "status": "published"
}

Product fields

• sku - product identifier, used as filename and URL slug, [a-z0-9-]+ only.
• title - product name, used in <h1> and as card title.
• short_description - meta description and card preview, around 150 characters.
• long_description - Markdown source for the product page body.
• category - slug of an existing category. One category per product.
• price_display - free-form text (£25.00, POA, From £40). No parsing.
• checkout_url - HTTPS URL to your external payment processor.
• images - array of {file, alt, is_primary} entries managed by the image manager.
• featured / hero_featured - flags for homepage placement.
• image_width / image_height / image_fit - per-product display sizing.
• status - published or draft. Drafts are hidden from listings, sitemap, and JSON-LD.

Categories have a similar small JSON file under /categories/ with slug, name, description (Markdown), optional banner image, sort order, and per-category image fitting.

Requirements & backups

• PHP 8.1 or later
• Apache with mod_rewrite (for clean URLs)
• HTTPS (the admin login requires it, and the buy-button flow assumes a secure context)
• SFTP access to the client site (for deploying the frontend and uploading the admin)
• GD extension (built into most PHP installs); Imagick supported as a fallback
• libsodium (built into PHP 8.1+) for licence verification

Tested on shared hosting (cPanel-style). No special privileges are required.

Backups are a folder copy

JSON files in /products/ and /categories/, plus uploaded media in /media/, are the only persistence - there is no database to dump and restore. A simple cron + rsync line on a backup machine handles it for any number of client sites:

# Daily 03:00 backup of one client's shop content and config
0 3 * * * rsync -az -e "ssh -p 22" \
  user@clientsite.com:/home/clientuser/public_html/shop/ \
  /backups/clientname/shop/

5 3 * * * rsync -az -e "ssh -p 22" \
  user@clientsite.com:/home/clientuser/shop-config/ \
  /backups/clientname/config/

Adapt to your preferred target, cloud sync, restic, tarballs, anything works because all state is files.