---
name: quickish-publish
description: >
  Give an HTML page a live URL on Quickish — and, when asked, give it a real
  backend. Use whenever the user wants to host, publish, or share an HTML page,
  slide deck, demo, portfolio, or one-pager (e.g. "publish this to Quickish",
  "host this page", "make this a live link"), OR wants that page to DO something:
  store data, sign in users, run server-side logic with a secret key, query a SQL
  database, or serve at their own domain. Quickish gives the page a URL at
  <handle>.quickish.site (personal) or <company>.quickish.space (work), public or
  private, with a zero-config backend (quick.db, quick.fn functions, quick.sql) on
  the same page. Static pages need no build step; framework apps (React/Vite/Astro)
  must be built first and the build output published. No server to run.
---

# Publishing (and building) on Quickish

Quickish hosts a folder of web files (HTML + CSS/JS/images/fonts) and serves it at
a Quickish URL — and that page can opt into a **zero-config backend** (a database,
server-side functions, real SQL) with no keys and no separate service. The simplest
unit is a **page**: a folder with an `index.html`. Each account has a **root page**
at the bare domain, plus optional **sub-pages** at `/<name>/`:

- Personal: `https://<handle>.quickish.site/` (root) · `…/<name>/` (sub-page)
- Workspace: `https://<company>.quickish.space/` (root) · `…/<name>/` (sub-page)

**Goal: do the work for the user.** When they say "publish this," produce one
self-contained `index.html` and publish it. When they say "build me a poll / a
kanban / a form that emails me," build the page *and* its backend (below) and
publish the whole thing. Hand back the live URL, not a list of files.

## Build the page first

- Output a folder containing **`index.html`** at its root. Inline the CSS and JS;
  a single self-contained file is the most robust. Keep everything to web assets;
  files over ~25 MB are skipped.
- Use **relative asset paths** (`./img/x.png`) or root-absolute (`/x.png`); the
  root page owns absolute paths, so both work.
- Add `<script src="/quick.js"></script>` to unlock the backend: `quick.db`,
  `quick.files`, `quick.identity`, `quick.realtime`, `quick.fn`, `quick.sql`. No
  keys needed.

## Icons (use the hosted set, don't hand-draw)

Quickish hosts a curated **Lucide** line-icon set (ISC, ~170 common icons) at a
stable path on every page — reach for it instead of pulling a random CDN, drawing
inconsistent SVGs by hand, or emoji. Two ways to use it:

- **Themeable (recommended)** — one cached fetch, inherits text color:
  ```html
  <svg width="20" height="20"><use href="/quick-icons/sprite.svg#search"></use></svg>
  ```
  Style with CSS (`svg{color:#3ef07f}` or `stroke`); the icons are `currentColor`.
- **Simple** — `<img src="/quick-icons/check.svg" width="20" alt="">` (not
  recolorable). Names are kebab-case Lucide names: `search` `menu` `x` `check`
  `arrow-right` `user` `download` `image` `play` `settings` `trash-2` `star` …
  `GET /quick-icons/icons.json` lists every available name.

Brand/social logos (GitHub, X, …) aren't in this set — use a brand-icon source if
you need those.

## Framework apps (React, Vite, Next, Astro, …)

Quickish hosts the **built static output**, not the framework source. If what you
made is a project with a `package.json` and a build step (a Vite/React/Astro/etc.
app), do **not** publish the source folder — the browser can't run `.tsx`/`.jsx`
or unbuilt modules, so it would 404 or render blank. Instead:

- **Build it, then publish the output folder:** run the build
  (`npm install && npm run build`) and publish the result, e.g. `quickish ./dist`
  (or `./build` / `./out`).
- **Or let the CLI build it for you:** run `quickish --build` in the project. With
  the user's permission it runs the install + build **on the user's machine** and
  publishes the output. If a `dist/` already exists, plain `quickish` detects it
  and publishes that automatically (no rebuild).

Only **static** output is hosted — server-rendered apps (Next SSR, Remix,
SvelteKit's node adapter) won't run; use the framework's static export/adapter.
When you can, a single self-contained `index.html` is still the most robust thing
to publish.

## Publish with the `quickish` CLI

This works end to end from a terminal and is the most reliable path.

1. Install once: `npm i -g quickish`
2. Sign in once: `quickish login` (opens a browser; the user signs in with Google
   and a token returns automatically. If headless, print the URL for them).
3. Publish the folder (or a single file):
   - **Home page**: `quickish ./my-deck` → `https://<handle>.quickish.site/`
   - **Single file**: `quickish ./index.html` → the file becomes the homepage.
     Any lone file works; an HTML file is served as `index.html`.
   - **A document** (a lone `.pdf`, `.md`, `.csv`, `.txt`, or image with no HTML)
     gets a built-in in-browser **viewer** automatically, with a Download button
     for the raw file — so `quickish ./report.pdf` just gives a real PDF reader at
     the URL. No wrapper page to build.
   - **Named sub-page**: `quickish ./my-deck deck` → `…/deck/`
4. The CLI prints the live URL. For a **personal** page it also prints a one-time
   "publish publicly" link; share it with the user, they click it once to accept
   the content policy and the page goes public. Updates never re-prompt.

The CLI publishes the **whole folder**, so any `functions/` and `sql/` directories
travel with it and deploy automatically (see "Add a backend" below).

**Visibility flags** (override the defaults below):

- `--private` only the owner
- `--invites a@co.com,b@co.com` private to the owner and the people listed
- `--workspace` anyone signed in at the company domain
- `--public` the world, via the one-time consent

## Publish via the assistant API (no shell needed)

If you can make HTTP calls but not run a shell, POST the page directly:

```
POST https://api.quickish.website/_assistant/publish
Authorization: Bearer <the user's publish token>
Content-Type: application/json

{ "html": "<the complete self-contained index.html>", "invites": ["a@co.com"] }
```

It returns `{ "url": "..." }`. The user gets their token from the dashboard
(Settings -> Publish with AI); setup is at quickish.website/connect. `page`,
`share`, and `invites` are optional.

## Overlay vs replace — how a re-publish treats other files

A publish runs in one of two modes:

- **overlay** (non-destructive) — writes the files you send and **keeps the rest**
  of the page untouched. This is the default for an **assistant `html`/`files`
  publish** and for a **CLI single file** (`quickish ./index.html`). Use it to
  change one or two files without disturbing the others.
- **replace** (destructive) — a full sync that **deletes anything not in your
  bundle**. This is the default for a **`zip`** (a complete build) and a **CLI
  folder** (`quickish ./dist`) — correct there, because stale build chunks must be
  swept. Force it with `mode:"replace"` / `--destructive`.

Practical guidance:

- **Updating a file or two → overlay** (the default for `html`/`files`). Don't send
  a partial set in replace mode — it removes everything you left out.
- **Shipping a fresh build / removing files → replace.** Before a destructive
  replace of a page **you didn't just author** (the user or another agent may have
  changed it), confirm with the user first; the live **URL** is the *rendered* page,
  not its source files, so don't reconstruct a publish from it. (A pull-the-source →
  edit → re-publish loop with publish-if-unchanged is coming.)
- **Data:** `quick.db` rows are **not** touched by any publish, but they're shared
  and may have changed. Read current rows (`quick.db.collection(...).list()`, or the
  connector's `db_query`) before an `update`/`remove` so a stale write doesn't
  overwrite another writer.

## Visibility (defaults, then confirm)

Defaults when you don't pass a flag:

- **Personal** page -> **public** (after the owner clicks the one-time consent link).
- **Workspace** page -> **company-visible** (anyone signed in at the same domain).

For fine-grained, per-person access use `--invites` (or the `invites` field on the
API). Always confirm the intended audience before publishing something company-wide
or public.

## Add a backend (zero-config)

With `<script src="/quick.js"></script>` on the page, the same site gets a backend —
no provisioning, no keys, scoped to that page. Reach for the smallest piece that fits.

### quick.db — a document store

```html
<script src="/quick.js"></script>
<script>
  const tasks = quick.db.collection("tasks");
  await tasks.create({ title: "Ship it", done: false });
  const all = await tasks.list({ where: { done: false }, order: "-created_at", limit: 20 });
  await tasks.update(all[0].id, { done: true });
  tasks.subscribe({ onCreate: t => console.log("new", t) }); // live over websockets
</script>
```

- A collection is **owned by the page** that creates it. Default access: **read by
  the page's audience, write by the owner** — so a public page can show data without
  letting visitors change it. Set per-op rules when you declare it:
  `quick.db.collection("comments", { read: "audience", create: "users", update: "author", delete: ["author","owner"] })`.
  Principals: `owner · audience · author · users · workspace · public` (`write` =
  create+update+delete).
- Also available: `quick.files` (uploads — see below), `quick.identity()` (the
  signed-in visitor), `quick.realtime(channel)`, `quick.cast()` (turn the page into
  a screen pushed to from a phone).
- **Org directory (workspaces):** `quick.org.sites()` (= `quick.db.collection("org_sites").list()`)
  returns the org's visible sites with **live hit counts** — each
  `{ id, name, url, owner, visits, visibility }` — kept current as teammates publish.
  Build a dynamic company directory/homepage with zero data wiring.
- **Sample data for remixes:** `quick.db.collection("cards", { seed: true })` seeds
  those docs into every remix so a copy works on first run.

### Prebaking — render quick.db into the page for SEO

When a **public** page lists quick.db content that needs to be crawlable (a blog,
catalog, docs index, changelog, directory, landing page), don't render it with
client-side JS — search engines and link-preview bots fetch the HTML and see an
empty shell. Instead write the list as a `<template quick-each="…">` block.
Quickish **pre-bakes** it at publish: it runs the query, expands the rows into
static HTML in place, and inlines the data as a hydration island so `quick.js`
takes over with no flash. Crawlable, fast, zero framework — automatic, no flag.

```html
<ul>
  <template quick-each="posts" quick-order="-published_at" quick-limit="20">
    <li><a href="/blog/{{slug}}">{{title}}</a> — <time>{{published_at}}</time></li>
  </template>
</ul>
```

- Attributes: `quick-each="<collection>"` (required), plus `quick-order` (a field;
  prefix `-` for descending), `quick-limit`, `quick-offset`, and `quick-where`
  (a JSON filter, e.g. `'{"published":true}'`). Interpolate row fields with
  `{{title}}` / `{{author.name}}` (dotted paths); every value is HTML-escaped for you.
- **Only public-readable collections bake.** Declare the collection
  `read: "public"` — the default is `audience`, which is *not* baked — so private
  data can never be frozen into the shared static HTML; non-public directives are
  skipped. (Prebaking is for content that's public anyway; that's the whole point —
  letting crawlers see it.)
- **Freshness — the baked HTML is a publish-time snapshot.** On first paint
  `quick.js` renders the baked rows from the inlined island (no flash); your own
  `list()` / `subscribe()` then go live, so **JS visitors** see rows added after
  publish. But the **crawlable static HTML stays as it was baked** until the page
  is re-baked — today that means **re-publishing**. So if the user adds indexable
  content at runtime (a new blog post via the app), the page must be re-published
  for crawlers to see it: new rows render live for humans, but won't appear in
  `view-source` until then.
- Pattern: write the list as `<template quick-each>` *and* still render it from
  `list()` in your JS. The island makes that first render free (no fetch), and the
  live path keeps it current for visitors. Caps: 100 HTML files / 200 directives
  per publish.

### quick.files — user uploads (images, video, PDFs)

Let visitors (or the owner) upload files and get back a **stable URL** you can drop
straight into an `<img>`/`<video>` `src`. Bytes are stored durably and served from
the edge — no S3, no upload server.

```js
const { url } = await quick.files.upload(fileInput.files[0]);
img.src = url;                                   // ready to render
```

- **Buckets reuse the quick.db permission model.** A bucket is named (`{ bucket: "post-media" }`,
  default `"default"`) and takes the same policy shape as a collection — **default
  is `write: "owner"`, `read: "audience"`**, so UGC is opt-in. Open it up explicitly:
  `quick.files.upload(file, { bucket: "post-media", policy: { write: "users", read: "public" } })`
  lets any signed-in visitor upload and anyone view. `policy` only takes effect on
  the **owner's** first call (or `quick.files.bucket(name, policy)`).
- **API:** `upload(file, opts) → { id, url, name, bytes, contentType }`,
  `list(opts) → [...]` (with `_mine` per file), `delete(id, opts)`,
  `url(id, opts)` (the stable path), `bucket(name, policy)` (declare a policy).
- **Allowed types:** PNG/JPEG/GIF/WebP/AVIF, PDF, MP4/WebM/MOV. (SVG and HTML are
  rejected — they can carry script.) Per-file cap is generous (100 MB); total usage
  counts toward your plan's storage.
- **Public files are crawlable + cacheable**; video is served with HTTP Range so it
  scrubs. For a blog with uploaded images, a `read: "public"` bucket pairs naturally
  with prebaking.

### quick.fn — server-side functions (secret keys, trusted writes)

When the page needs logic the browser can't be trusted with — call a paid API with a
secret key, make a write the public can't forge, validate input — drop a file in a
`functions/` folder. **One top-level file = one function**, named by filename;
sub-folders (e.g. `functions/lib/`) are shared modules. The code is stored
server-side and never shipped to the browser, and it deploys automatically with
`quickish`.

```js
// functions/checkout.js
export const config = {
  env: ["STRIPE_SECRET"],                  // secret names (values set out of band)
  db:  { orders: "write" },                // collections it may touch (trusted writer)
  egress: ["api.stripe.com"],              // hosts it may call out to (off by default)
};
export default async function (req, { env, db, identity, fetch }) {
  const me = identity();                   // signed-in visitor or null
  const order = await db.collection("orders").create({ user: me?.email, items: req.body.items });
  return Response.json({ ok: true, id: order.id }); // or return a plain object / string
}
```

Call it from the page: `await quick.fn("checkout", { items })` (POSTs by default,
resolves to JSON or text). The injected `db` is a `quick.db` pre-scoped to
`config.db` — it can write owner-only collections a public visitor can't. Secret
**values** are set out of band (CLI-authenticated `POST /_cli/fn-secrets` with
`{ name, value }`; a `quickish secrets` command is coming) — only the names appear
in `config.env`. Each call runs sandboxed with comfortable caps (64 MB, 10 s).

### quick.sql — zero-config relational SQL

When data has real relations (a leaderboard, a kanban with `group by`/`order by`),
use `quick.sql`. Declare the schema as ordered `sql/*.sql` files next to the page;
they apply at deploy, exactly once each, as your site's own least-privilege Postgres
role (each site gets an isolated schema — cross-site is impossible). Query from the
page with a tagged template; interpolated values are **always bound params**, never
spliced in:

```sql
-- sql/001_init.sql  (deployed automatically with quickish)
create table if not exists scores (id serial primary key, name text not null, points int not null default 0);
```
```js
const top = await quick.sql`select name, sum(points) as pts from scores group by name order by pts desc limit 10`;
```

The browser path is **read-only** (a single `select`/`with`, row-capped). **Writes**
come from migrations (at deploy) or from a `quick.fn` function holding the write —
so a public page can read the leaderboard while only your logic changes it. Use
`quick.db` for "just store some JSON"; `quick.sql` when you actually have relations.

## Custom domains

A published page can serve at the user's own host (e.g. `docs.acme.com`) with an
automatic HTTPS cert, applying the same access rules as the Quickish URL. Bind the
host to a page, then add two DNS records it returns: a **CNAME** to `quickish.website`
(a sub-domain) or an **A** record to the Quickish IP (an apex), plus a **TXT** at
`_quickish-challenge.<host>` = `quickish-domain-verify=<token>` to prove ownership;
verify and it goes live. Binding is owner/editor-gated via the CLI-authenticated API
(`POST /_cli/domains` then `POST /_cli/domains/verify`); a `quickish domains` command
is on the way.

## Free vs paid (so you don't surprise the user)

- **Free** = publish as many pages as you like, but only the **latest** one stays
  live; the rest go dormant until the owner upgrades. So a new publish becomes the
  live page.
- **Paid** (Personal $7.99/mo, Workspace $99/mo) keeps every page live at once.

## After publishing

- **Update:** re-run the same publish; the page (and its `functions/` + `sql/`)
  replaces in place. Public pages stay public, no re-consent.
- **Share:** give the user the live URL. Personal public pages need the one-time
  consent click before others can see them.

## Google Drive (coming soon)

Sharing a Drive folder with Quickish to auto-host and sync it is coming soon. For
now, publish with the CLI or the assistant API above.