Simon James
14 KiB
Qortal Web Builder
A monorepo of Q-Apps for the Qortal ecosystem — decentralized websites and commerce on the Qortal Data Network (QDN), loaded through the Qortal Hub.
This repository contains three related applications that share one core codebase:
| App | Folder | Role |
|---|---|---|
| Qortal Web Builder (QWB) | repo root (src/) |
Visual editor — build and publish websites to QDN |
| Qortal Web | qortal-web-app/ |
Public discovery engine — browse everything QWB publishes |
| Q-Shops | q-shops-app/ |
Marketplace aggregator — browse and buy from many Q-Shops at once |
All three run as static Q-Apps: a zip of HTML, JS, CSS, and assets that the Hub loads locally. Blockchain and QDN access go through qortalRequest (the Hub bridge), not a custom backend server.
How the three apps fit together
┌─────────────────────────────────────────────────────────────────┐
│ Qortal Web Builder (QWB) │
│ You design blocks → publish WEBSITE + QDN resources │
└───────────────┬─────────────────────────────┬───────────────────┘
│ │
▼ ▼
┌────────────────────────┐ ┌──────────────────────────────┐
│ Published WEBSITE │ │ Qortal Web index DOCUMENT │
│ (visitor-facing site) │ │ (.__qwb__/qortal-web-index) │
└────────────────────────┘ └──────────────┬───────────────┘
│
▼
┌────────────────────────────────┐
│ Qortal Web │
│ Search · Discover · Open │
└────────────────────────────────┘
QWB Q-Shop block ──► catalog manifest on QDN ──► Q-Shops app
(per-shop + optional directory snapshot)
- QWB is where sites are created and published.
- Qortal Web reads index files that QWB publishes alongside each site, then lets anyone search and open websites, forums, articles, media, folders, and more.
- Q-Shops reads Q-Shop catalog manifests from many publishers and presents a unified marketplace with cart, checkout, and order history.
Qortal Web Builder (QWB)
What it is: A Mobirise-style block editor for Qortal. You compose a site from draggable blocks, tune themes and pages, then publish to QDN as a WEBSITE resource (and related DOCUMENT/JSON payloads).
Who it is for: Site owners, creators, and merchants who want a full website on Qortal without writing code.
Core workflow
- Open QWB in the Qortal Hub (load the Q-App zip).
- Authenticate with your Qortal wallet so publishes are signed on-chain.
- Add blocks from the block library — header, hero, text, galleries, interactive blocks, etc.
- Configure pages, navigation, themes, and per-block options in the inspector.
- Save a draft locally (browser) and/or to QDN as a DOCUMENT.
- Publish Website — builds a
website.zip, uploads WEBSITE + peer JSON (forum, poll, comments), Q-Shops index, and the Qortal Web index when applicable.
Published sites are static SPAs with a visitor runtime: guests browse freely; Authenticate unlocks posting, voting, checkout, and other wallet-gated actions.
Block types
Layout & content
| Block | Purpose |
|---|---|
| Banner | Rotating announcement bar |
| Header | Logo, site title, main navigation |
| Hero | Title, intro, call-to-action |
| Countdown | Timer with on-complete actions |
| Text | Rich text (headings, links, embedded media) |
| Buttons | Linked buttons (qortal://, external URLs) |
| Multi-column | Image + heading + description grids with section CTA |
| Photo | Single image, fullscreen viewer |
| Albums | Photo galleries with layouts and lightbox |
| Video | Upload or Q-Tube embed |
| Music | Albums and on-page player (Q-Music integration) |
| Map pins | Map with coordinate pins and photos |
| Q-Apps | Embed other Q-Apps in tabs or a grid |
| Links | Quick link list |
| Footer | Credits and footer links |
Interactive & commerce (data stored on QDN as signed JSON / resources)
| Block | Purpose |
|---|---|
| Comments | Visitor comments with moderation |
| Forum | Topics, replies, votes, archiving |
| Vote / poll | Polls with eligibility rules and on-chain-style votes |
| Folders | File library — publish to Q-Share, Q-Tube, Q-Music; PDF/image viewers |
| Q-Shop | Full storefront — catalog, cart, checkout, digital downloads, merchant tools |
| Newsletter | Q-Mail subscriber list and campaigns |
| Contact form | Encrypted Q-Mail to the site owner |
| Groups | Join a Qortal group; live member count |
| Articles | Long-form articles with Q-Blog sync and comment threads |
Publishing & access control
- Global sites are listed on Qortal Web for everyone.
- Group-only sites restrict the published WEBSITE to members of a chosen Qortal group; Qortal Web shows them only to authenticated group members (index carries
websiteAccessMode+websiteAccessGroupId). - Discover listing can be toggled per site; QWB writes a Qortal Web index DOCUMENT (
.__qwb__/qortal-web-index.json) so Qortal Web can index forums, polls, articles, media, folders, and the site itself.
Q-Shop inside QWB
The Q-Shop block is a complete storefront: categories, variants, coupons, shipping vs pickup vs digital, QORT / Q-Asset payments via Hub, order invoices, and merchant ledger tools. Catalog data is published to QDN so Q-Shops (and Qortal Web) can discover it.
Technical notes
- Source:
src/, entrydev.html(builder),site.html(published visitor preview path). - State: Zustand (
src/store/builderStore.ts); drafts inlocalStorage+ optional QDN DOCUMENT. - Hub API:
src/lib/qortalClient.ts→qortalRequestactions (PUBLISH_QDN_RESOURCE,SEARCH_QDN_RESOURCES, etc.). - See QORTAL-HUB.md for zip layout, WEBSITE vs APP routing, auth troubleshooting, and grey-screen fixes.
Build & release zip
npm install
npm run build
bash scripts/zip-portfolio.sh # → Portfolio-Q-App-v3-YYYYMMDD.zip
Qortal Web
What it is: The Qortal Web Engine — a discovery and search front-end for content published through QWB. It scans QDN for QWB index DOCUMENTs, merges them into a searchable catalog, and lets users browse by category or query.
Who it is for: Anyone exploring the Qortal web — finding websites, reading articles, opening forums, watching indexed videos, browsing shared folders, etc.
What it indexes
Each QWB site can publish a structured index (qortal-web-index-v1) listing entries such as:
- website — the site itself (title, logo, preview image)
- forum, poll, article — interactive blocks (opens in embedded published-site viewers)
- video, music, photo, albums — media blocks
- folder, library — Share Folders / file listings
- qshop — linked storefront catalog entries
Main features
- Home — stats, top publishers, discover website cards, global search.
- Category browse — filter by content kind (websites, forums, articles, video, music, folders, etc.).
- Search — full-text search across indexed titles and descriptions.
- Content viewer — opens the target in-context: full site embed for websites, hybrid block-focus embeds for forum/poll/article (real published visitor runtime), native media viewers where appropriate.
- Authenticate — Hub wallet sign-in for group-gated sites, masthead identity, and interactive embeds that need a session.
- Group-only visibility — sites published as group-only appear only if the signed-in account is a member of that group.
- Open in Qortal — jump to
/render/WEBSITE/{publisher}in the Hub.
Qortal Web imports shared code from QWB (@qwb/core, @qwb/visitor) via Vite aliases — it is not a standalone package; clone and build from this monorepo root.
Build & release zip
npm install # root deps (shared with QWB)
npm --prefix qortal-web-app install
npm --prefix qortal-web-app run build
bash scripts/zip-qortal-web-app.sh # → Qortal-Web-v0.0.29-YYYYMMDD.zip
Q-Shops
What it is: A marketplace aggregator Q-App that collects Q-Shop catalogs published by QWB sites across QDN and presents them in one unified UI — browse many shops, add to cart across vendors, checkout with Hub payments, and track orders.
Who it is for: Buyers who want one place to shop all Qortal Web Builder stores; complements the per-site Q-Shop block on individual websites.
How discovery works
- QWB site owners publish a Q-Shop block and include catalog manifests on QDN (
qwb-qshops-catalog-v1and related DOCUMENTs). - Q-Shops searches QDN for these manifests and merges them into a live directory.
- Optional directory snapshots (
qshops-directory-snapshot-v1) from curators federate listings when SEARCH alone is sparse on a given Hub node. - The catalog refreshes periodically and when you return to the tab so prices, stock, and new shops stay current.
Main features
- Marketplace browse — grid and list views, category filters, shop gallery with hero imagery.
- Product detail — variants, gallery, shipping/digital tabs, quick add.
- Multi-vendor cart — line items grouped by shop; checkout per vendor or combined flow.
- Checkout — shipping vs pickup vs digital-only; delivery map (Leaflet + bundled tiles); encrypted buyer profile on QDN (same identifier family as QWB checkout).
- Payments —
SEND_COIN/ Q-Asset transfer via Hub; payment overlay designed so Hub signer dialogs are not blocked by the Q-App UI. - Q-Mail receipts — seller notification and buyer receipt after successful payment.
- Digital goods — download
qortal://FILE/…products after payment. - My orders — persisted per wallet; invoices with re-download for digital lines.
- Authenticate — required for checkout, saved shipping, and order history.
Build & release zip
npm install
npm --prefix q-shops-app install
npm --prefix q-shops-app run build
bash scripts/zip-q-shops-app.sh # → Q-Shops-v0.0.45-YYYYMMDD.zip
Repository layout
qortal-web-builder/
├── src/ # QWB application source (builder + published block views)
├── packages/qwb-visitor/ # Shared visitor runtime (used by QWB, Qortal Web, embeds)
├── qortal-web-app/ # Qortal Web Q-App
├── q-shops-app/ # Q-Shops Q-App
├── scripts/ # Build, sync dist, zip helpers
├── public/ # Static assets shipped with QWB
├── dev.html # QWB Vite dev/build entry (builder UI)
├── site.html # Published visitor site entry (export path)
├── QORTAL-HUB.md # Hub deployment & troubleshooting
└── CHANGELOG.md # QWB release notes
Not in git (see .gitignore): node_modules/, dist/, extracted/, release *.zip files, generated root index.html / assets/ (produced by npm run build).
Getting started (developers)
Prerequisites
- Node.js 18+ (LTS recommended)
- Qortal Hub for testing Q-Apps with a real
qortalRequestbridge
Install
git clone https://gitea.qortal.link/simon/qortal-web-builder.git
cd qortal-web-builder
npm install
npm --prefix qortal-web-app install
npm --prefix q-shops-app install
Local development (optional)
Q-Apps are meant to run inside the Hub. Local Vite dev servers are useful for UI work but cannot complete wallet auth without the bridge:
npm run dev # QWB builder → dev.html
npm --prefix qortal-web-app run dev # Qortal Web
npm --prefix q-shops-app run dev # Q-Shops
For real QDN testing, always build + zip + load in Hub Preview.
Release zips (summary)
| App | Command |
|---|---|
| QWB | npm run build && bash scripts/zip-portfolio.sh |
| Qortal Web | bash scripts/zip-qortal-web-app.sh |
| Q-Shops | bash scripts/zip-q-shops-app.sh |
Zip contents must be flat (files at archive root: index.html, assets/, manifest.json, …). See QORTAL-HUB.md.
QDN & Hub concepts (short glossary)
| Term | Meaning |
|---|---|
| QDN | Qortal Data Network — on-chain storage for DOCUMENT, WEBSITE, IMAGE, JSON, etc. |
| Q-App | Static app package (zip) registered and loaded by the Hub |
| WEBSITE | Published site zip — visitor-facing pages |
| DOCUMENT | JSON or text resource (drafts, indexes, manifests) |
| qortalRequest | JavaScript API injected by the Hub for wallet + QDN operations |
| Registered name | Human-readable Qortal identity tied to an address (used for publishing and avatars) |
Official references: Q-Apps.md, qortal.dev Q-Apps, Qortal API docs.
Contributing & version control
Changes are not pushed to Gitea automatically. After editing:
git add -A
git commit -m "Describe your change"
git push
Changelogs:
- QWB —
CHANGELOG.md - Qortal Web —
qortal-web-app/CHANGELOG.md - Q-Shops —
q-shops-app/CHANGELOG.md
License
No license file is included yet. Add one in Gitea if you intend to open-source or clarify usage terms.