Skip to main content

Create your own Popfold site

Alpha. Formats and commands still change between releases.

This walks through a new site from nothing to a built dist/. It is written for a person or an agent. Read guide.md first for the words used here. Paths are relative to the Popfold folder.

1. Decide the story before the 3D​

Popfold is a story with one beat per screen. Write the beats down first:

#Section idWhat the visitor readsWhat the home does
0topThe promiseClosed, floating
1approachHow you thinkOpens, the first room fills in
2servicesWhat you doThe second room
3buildProofThe third room
4processThe stepsEverything open, pulled back
5contactThe askCloses again

Five to nine beats works well. Then pick the shell that fits:

  • Compact: three rooms of about equal weight. Friendly, toy-like. Needs no modelling. Start here.
  • Diorama: you have (or will model) one real room. Three zones inside it.
  • Tower: many beats in a line, such as a career, a product stack or a process. One floor per beat.

2. Copy the template​

templates/compact is a complete small site: an office in a box, six sections, no model files. templates/tower is another, for a long story told top to bottom: a studio in a four-floor building.

popfold init makes a new site from it, in a folder of its own:

node bin/popfold.mjs init ../mysite --port 5200 # add --template tower for the tower
cd ../mysite
pnpm install
pnpm dev

The new folder is a git repository with nothing committed yet. It holds Popfold in popfold/ as a git submodule on the newest release (--ref <tag or branch> picks another; --from <git url or folder> takes Popfold from somewhere other than this checkout's remote), the template's files from that same release, a package.json named after the folder (--name to choose), and a pnpm-workspace.yaml that lists popfold. Updating Popfold later is pnpm exec popfold update.

The rest of this page walks through the compact template. The tower template has the same files; its README.md says what differs. For a diorama, start from the compact template and replace the recipe in src/home.ts with a diorama block (the guide shows it); a diorama template is planned.

3. The files, one by one​

package.json​

{
"name": "mysite", "private": true, "version": "0.0.1", "type": "module",
"scripts": {
"dev": "vite --port 5182 --strictPort --host 127.0.0.1",
"typecheck": "tsc --noEmit",
"build": "tsc --noEmit && vite build",
"build:static": "tsc --noEmit && popfold build"
},
"dependencies": { "popfold": "workspace:*", "three": "^0.187.0" },
"devDependencies": { "@types/node": "^22.20.5", "@types/three": "^0.187.0", "typescript": "^7.0.2", "vite": "^8.3.8" }
}

index.html​

The parts Popfold relies on:

<body>
<div class="bg" aria-hidden="true"></div>
<canvas id="scene" aria-hidden="true"></canvas>
<main id="main">
<section class="stage" id="top" data-text="left">
<div class="card">
<h1>One line that says what you do.</h1>
<p>Two sentences.</p>
</div>
</section>
<!-- one <section class="stage" id="…"> per beat, in story order -->
</main>
<script type="module" src="./src/main.ts"></script>
</body>

Rules:

  • Every beat is a <section class="stage"> with a unique id.
  • The sections sit in <main id="main">. main.ts watches that element to know when the page's height changes.
  • Each section has an <h1> or <h2>. The simple page and llms.txt use it as the section's title.
  • The copy sits in one wrapper (<div class="card"> or <article>). Stories are written in before its closing tag.
  • data-text="left|right|center" says where the text card sits. Set the keyframe's side to the opposite (data-text="left" goes with side: 1).
  • The canvas is fixed behind the page: #scene { position: fixed; inset: 0; width: 100vw; height: 100lvh; z-index: -1; }
  • A click on the empty part of a .stage section reaches the home. A click on anything else (your card, your header) does not. Change that with the isOverUi option if your page is built differently.

src/home.ts: the code a home needs​

The home itself is data, in src/home.json (next). This file adds the one thing data cannot hold: how each kind of piece is built.

import { P, homeFromFile } from 'popfold';
import json from './home.json';

export const { recipe: HOME, beats: BEATS } = homeFromFile(json, {
// how to build each kind the file names (a kind that is a model file in `props` needs no entry here)
kinds: { sofa: () => P.sofa(), 'coffee-table': () => P.coffeeTable(), plant: () => P.plant(), bed: () => P.bed() },
// props: ['lamp'], // model files, if the home has any: public/models/props/<name>.glb
});

homeFromFile() checks the file and reports a mistake in words, then gives back the home (recipe, for homes: [HOME]) and its story (beats). For a tower, the building's own colours and its pipe go here too: homeFromFile(json, { kinds, tower: { wall, slab, spine: { color } } }).

src/home.json​

The home as data: its look, its story and what is in it. No code, so vite.config.ts, the popfold command and the studio can all read it, and an editor that knows JSON Schema checks it as you type ($schema points at Popfold's schema/home.schema.json).

{
"$schema": "../popfold/schema/home.schema.json",
"id": "my-home",
"name": "My home",
"blurb": "One line for the studio.",
"look": {
"base": "#1E2A44",
"lid": "#1E2A44",
"heart": "#FF6B4A",
"leftSlab": "#EFE6D8",
"rightSlab": "#EFE6D8",
"centerFloor": { "pattern": "checker", "colors": ["#EFE6D8", "#FBF8F3"], "count": 8 },
"lidPaper": { "pattern": "stripes", "colors": ["#FBF8F3", "#EFE6D8"], "count": 10 },
"leftFloor": { "pattern": "dots", "colors": ["#EFE6D8", "#FF6B4A"], "count": 6 },
"leftWall": "#FBF8F3",
"rightFloor": { "pattern": "terrazzo", "colors": ["#FBF8F3", "#FF6B4A", "#FFD66B"] },
"rightWall": { "pattern": "waves", "colors": ["#FBF8F3", "#9CC3E6"], "count": 7 }
},
"emblem": { "title": "my", "subtitle": "studio", "heart": false },
"beats": [
{ "id": "top", "name": "Closed", "camera": [0, 4.4, 11.5], "lookAt": [0, 0.7, 0], "set": { "hero": 1, "side": 1 } },
{ "id": "approach", "name": "Centre room", "camera": [0, 4.6, 11], "lookAt": [0, 1.7, 0], "set": { "c": 1, "glow": 0.8, "side": -1 } },
{ "id": "services", "name": "Left room", "camera": [-2.6, 3.6, 7.2], "lookAt": [-4.1, 1.1, -0.2], "set": { "c": 1, "L": 1, "glow": 0.4, "side": 1 } },
{ "id": "contact", "name": "Folded", "camera": [0, 4.2, 12.5], "lookAt": [0, -1.3, 0], "set": { "hero": 1 } }
],
"pieces": [
{
"id": "sofa", "room": "center", "kind": "sofa", "at": [0, -1.3],
"story": { "title": "Where we start", "text": "Every project begins with a conversation.", "tags": ["Discovery"] }
},
{ "id": "coffee-table", "room": "center", "kind": "coffee-table", "at": [0, 0.45] },
{ "id": "plant", "room": "left", "kind": "plant", "at": [-1.2, -0.9] },
{ "id": "bed", "room": "right", "kind": "bed", "at": [0, -0.4], "turn": 1.571 }
]
}

look is the compact's case and rooms: five colours (base, lid, heart, and the two side rooms' slabs), and six surfaces (the three floors and the three walls; lidPaper is the centre room's back wall). A surface is a plain colour or a pattern, checker, stripes, dots, waves or terrazzo, with its colours and how many across. "shell": "crisp" gives the case square edges. emblem is the wordmark on the lid. A tower has no look; its floors carry their own colours.

beats is the story: one beat per section of the page, in the same order, each with its section's id. set says what the home does there (c, L, R: how far the centre, left and right rooms are open; glow; badges; hero; side), and anything left out is 0. camera and lookAt are where the camera is and the point it looks at. Do not guess them: in the studio, scrub to the beat, switch the camera to Free orbit, frame the shot and press Use for "", which writes both into this file. Without a browser, change the numbers a little at a time and take a picture after each change with pnpm exec popfold shot --stage <n>.

at is [x, z] on the floor, or [x, height] with "wall": true. turn is in radians: 1.571 is a quarter turn, 3.142 half. A tower's file also has "floors", and a piece's room is a floor's id. Every field is described in the schema.

Keys: a compact's rooms are center, left and right, with -wall for wall pieces (center-wall/whiteboard). Give them your own names with rooms: { center: 'studio', … } in the recipe. A diorama's keys are <zone>/<piece>; a tower's are <floor id>/<piece>. To see every key a home has, open the studio's Props list.

Keep this file free of 3D code. vite.config.ts imports it, and the config must not load the engine.

src/main.ts​

Copy it from the template. It is 35 lines and does four things:

  1. calls scrollStage() from popfold/fallback, which turns the scroll position into a stage number and measures the sections again whenever the page changes height;
  2. calls shouldStart3D(); if no, markFallback() and stop;
  3. loads popfold, the recipe and the beats, and calls startScene({ canvas, homes, home, beats, getStage, reducedMotion, avatar: false, onStory, onPick });
  4. calls markReady(canvas) and viewToggle().

Change the home it imports, and the section ids in onPick (a click on the centre, left or right room scrolls to that section). Add lighting: { … } and storyDot: '#…' to give the site its own light and dot colour, and pass the same to the studio. The story card takes its colours from CSS variables (--pf-card-bg, --pf-card-ink, --pf-card-accent, --pf-card-tag) that you set on :root in src/style.css.

studio.html and src/studio.ts​

studio.html is the same in every site. src/studio.ts:

import { mountStudio } from 'popfold/studio';
import { BEATS, HOME } from './home';

mountStudio({
homes: [HOME], beats: BEATS,
avatar: false,
pickStages: { center: 1, left: 2, right: 3 },
siteUrl: './',
});

vite.config.ts​

import { defineConfig } from 'vite';
import { layoutSaver, popfoldFallback } from 'popfold/vite';

export default defineConfig({
base: './',
plugins: [
layoutSaver({ home: 'src/home.json' }), // the studio's Save writes moved pieces into the home file
popfoldFallback({
siteName: 'My Studio',
siteUrl: 'https://example.com/', // optional: enables og:image, canonical and sitemap.xml
homeFile: 'src/home.json', // its pieces' stories, and its id for the stills
sections: { center: 'approach', left: 'services', right: 'build' }, // room or zone -> section id
}),
],
build: { target: 'es2020', assetsInlineLimit: 0, rollupOptions: { input: { main: 'index.html', studio: 'studio.html' } } },
});

4. Work in the studio​

pnpm dev # then open the address it prints, with /studio.html
  1. Scrub the story. Fix keyframes until each stop frames its room.
  2. Tick Pick in view, click pieces, nudge them, Save layout: each moved piece's line in src/home.json changes. Add a piece and Remove… put pieces on the list and take them off.
  3. Check Evening light and the phone width.
  4. Capture stills (or run pnpm build:static, which does it for you).

5. Add real models​

Replace built-in pieces one at a time with .glb files. models.md covers every way to get one. Add each name to the recipe's props and use gen('name', size) ?? P.something() so the site still works if a file is missing.

6. Build and check​

pnpm build:static

Check before you call it done:

  • pnpm exec popfold check finds nothing wrong (one beat per .stage section, in the same order).
  • pnpm typecheck passes.
  • dist/index.html opened with ?view=simple shows a still and the stories in every section.
  • dist/llms.txt reads like the page.
  • The page works at phone width, and with reduce motion switched on in the operating system.
  • Every third-party model is listed in the site's CREDITS.md with its creator and licence. popfold check warns about any model in public/models/ that CREDITS.md does not name by path, file name or folder.
  • No placeholder copy in [brackets] is left.

7. Publish​

Upload dist/ to any static host. Paths are relative, so a sub-folder works. Set siteUrl in popfoldFallback() to the real address before the final build, so the share image and sitemap are right.