⬇ Get the kit

The download is the engine — scripts, manifest, Vercel config, OG function, and agent docs. Unzip it, point it at your domain, push to git. The harness tabs below teach your assistant how to publish once the engine is live.

⌘ Wire up your agent

Pick your harness. Each tab installs what your assistant needs — /publish for day-to-day publishing, plus a background skill/rule for conventions.

Cursor Claude Code

/publish

Slash command — say /publish my notes to scaffold a new shareable or refresh an existing page. If the engine isn't set up yet, it walks you through this guide instead of failing.

shareables rule

Background workflow rule — teaches Cursor the publish command, OG conventions, and privacy model whenever you ask to share something.

Both use Cursor's deeplinks — one-click install. Adjust the mirror path in the rule if yours isn't ~/.scratchpad/.shareables.

/publish command

Install the slash command so /publish scaffolds or updates shareables from your scratchpad.

copymkdir -p ~/.scratchpad/commands
cp ~/.scratchpad/.shareables/commands/publish.md ~/.scratchpad/commands/publish.md

Or fetch directly from this site before you've unzipped:

copymkdir -p ~/.scratchpad/commands
curl -fsSL https://shareables.yahyatarique.dev/shareables/self-host/commands/publish.md \
  -o ~/.scratchpad/commands/publish.md

shareables skill

Background skill — triggers on “share this / publish this / put this on shareables” and loads the full workflow docs.

copymkdir -p ~/.scratchpad/skills/shareables
cp ~/.scratchpad/.shareables/SKILL.md ~/.scratchpad/skills/shareables/SKILL.md

Or fetch from this site:

copymkdir -p ~/.scratchpad/skills/shareables
curl -fsSL https://shareables.yahyatarique.dev/shareables/self-host/SKILL.md \
  -o ~/.scratchpad/skills/shareables/SKILL.md

⚙ Set it up (~10 min)

Prereqs: Node 18+, a Vercel account, a domain (or *.vercel.app), and git. No local Chrome — OG cards render on Vercel at request time.

1. Put the kit where your pages will live

   Unzip into a “mirror” folder that becomes a git repo Vercel deploys.

   copymkdir -p ~/.scratchpad/.shareables && cp -R shareables-starter-kit/* ~/.scratchpad/.shareables/ && cd ~/.scratchpad/.shareables
   npm install

2. Point it at your subdomain

   The placeholder is shareables.example.com — swap in shareables.<your-domain> (not your apex/root domain, unless shareables is the only thing on it):

   copy# macOS (use `sed -i` without '' on Linux)
   find . -type f \( -name '*.js' -o -name '*.mjs' -o -name '*.json' -o -name '*.md' -o -name '*.cjs' \) \
     -exec sed -i '' 's/shareables\.example\.com/shareables.unveil.skin/g' {} +

3. Push to git & import on Vercel

   copygit init && git add -A && git commit -m "init shareables"
   git remote add origin git@github.com:<you>/shareables.git && git push -u origin main

   In Vercel: New Project → import the repo. Accept defaults — vercel.json sets installCommand: npm install for the OG function deps. Add your domain under Settings → Domains. Every push to main auto-deploys.

4. Wire up your agent

   Use the harness tabs above — install /publish and the skill/rule for Cursor or Claude Code.

5. Publish your first page

   Either run /publish in your agent, or invoke the script directly:

   copynode scripts/publish.mjs \
     --file ~/.scratchpad/hello.html --project "Demo" --title "Hello, shareables" \
     --desc "My first self-hosted shareable."

   Copy in → manifest → build → commit → push → prints your live URL. The OG card appears on first fetch.

⚡ Real-time interactivity (optional)

Static pages, plus an opt-in shared key-value store when a page needs live state — votes, flags, reactions, counters, RSVPs, polls — across visitors.

1. Provision Upstash KV & set env vars

   Add an Upstash KV store (Vercel Marketplace, free tier) and set KV_REST_API_URL + KV_REST_API_TOKEN under Settings → Environment Variables. Without them, api/flags.js returns 501 live store not configured and the rest of the site is unaffected.

2. Mark the page live

   Publish with --live (or set "live": true in shareables.json). build-index.cjs compiles every live page into lib/live-pages.js — the store's write allowlist. The pageId is <projectSlug>-<slug>.

3. Set SHAREABLES_SESSION_SECRET for accounts

   Live actions require a signed-in account, so set SHAREABLES_SESSION_SECRET (any long random string). Optionally set SHAREABLES_USERNAME + SHAREABLES_PASSWORD for an admin login. Visitors self-serve at /login → Create account (stored in the same Upstash KV).

4. Wire the page to lib/live-kv.js

   copyimport { createLiveStore } from "/lib/live-kv.js";
   const store = createLiveStore({ page: "demo-my-poll",
     onAuthRequired: () => location.href = store.loginUrl() });
   const me = await store.whoami();   // { loggedIn, role, name, email } | null
   store.subscribe((flags) => render(flags));   // { itemId: { count, mine, voters } }
   await store.toggle("item-1");

Two account roles: admin (env credential, full access) and visitor (self-serve email + password, can act on live pages but not browse gated pages). Both ship in the kit: login/, api/login.js, api/register.js, api/me.js, api/logout.js, lib/session.js, lib/users.js.

💡 Tips