glitterball

Connect a prototype

Put the Glitterball tag on a deployed prototype, or upload a build for Glitterball to host with the tag already on

A prototype is anything you can open in a browser: a Vercel or Netlify preview, a staging site, or a build you upload to Glitterball. Glitterball runs from a tag in the prototype's <head>, so a deployed prototype needs the tag. An uploaded build has it already.

Connect a deployed prototype

  1. In the web app at /app, choose Create walkthrough
  2. Choose where it lives: In code, In an app builder or A build. If the workspace already has prototypes, choose Add a prototype first.
  3. Pick the agent or app builder that makes it. You get its instructions: the line for a coding agent, the prompt for an app builder, or with Other or none, the commands to run yourself.
  4. Deploy the prototype and open it. The dialog waits until Glitterball sees it, then moves on to it.
  5. Choose Record it

Glitterball opens the prototype in a new tab with the Glitterball bar in its corner and Record ready. If nobody has claimed the prototype yet, recording claims it for you. See Record a walkthrough.

Already added one? Pick it in Create walkthrough and choose Record it.

Add the Glitterball tag

The quickest way is one command, run in the prototype's folder:

npx glitterball init
  1. It makes the prototype's own token and adds the tag, with that token, to the file that renders <head>: app/layout or pages/_document in Next.js, app/root in Remix, src/app.html in SvelteKit, your Astro layouts, index.html in Vite, or every page of a plain HTML site
  2. Run or deploy the prototype and open it. The Glitterball bar is in its corner.
  3. Press Record. The first time, a small window asks you to sign in or create an account and pick where the prototype goes: just you, your team, or a team people from your company are already on. Then you record.

Prefer to link it to your workspace from the terminal? Add --approve: it opens Glitterball in your browser to check a code and link the prototype first.

Run it again any time; it replaces the tag rather than adding a second one.

The tag is made for one prototype in your workspace, so each prototype gets its own. Keep the token in the tag: a tag without one gets a key from the site's address the first time it runs, and anyone who knows that address could claim it before you do. It works out which build a page is from the page's own files, so versions are told apart without anything to set. Once deployed, every visitor sees the Glitterball bar: the prototype's name (which lists its walkthroughs), the version, Record and Comment.

A page without the tag can't be recorded and can't show walkthroughs. See Add Glitterball to a prototype for all the ways in.

Comment on pull requests

If your team reviews changes in GitHub pull requests with preview deploys (Vercel, Netlify and most hosts), run this in the repository:

npx glitterball github

It adds a workflow that comments on each pull request once its preview is ready, linking the preview with the Glitterball bar on it, so reviewers can watch or record a walkthrough of the change. The comment updates on each new deploy. It uses the workflow's own GitHub token, so there's nothing to set up.

Upload a build

No live link? Upload the build and Glitterball hosts it at its own link.

  1. In Create walkthrough, choose Upload a build
  2. Pick a .zip of your output folder (dist, out or build) or a single .html file. The file can be up to 3 MB; leave out source maps and large media.
  3. Enter the Prototype name and choose Upload

Glitterball opens the hosted prototype in a new tab, ready to record. Hosted prototypes carry the Glitterball tag already.

Things to know about hosted builds: