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 id | What the visitor reads | What the home does |
|---|---|---|---|
| 0 | top | The promise | Closed, floating |
| 1 | approach | How you think | Opens, the first room fills in |
| 2 | services | What you do | The second room |
| 3 | build | Proof | The third room |
| 4 | process | The steps | Everything open, pulled back |
| 5 | contact | The ask | Closes 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 uniqueid. - The sections sit in
<main id="main">.main.tswatches that element to know when the page's height changes. - Each section has an
<h1>or<h2>. The simple page andllms.txtuse 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'ssideto the opposite (data-text="left"goes withside: 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
.stagesection reaches the home. A click on anything else (your card, your header) does not. Change that with theisOverUioption 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 "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:
- calls
scrollStage()frompopfold/fallback, which turns the scroll position into a stage number and measures the sections again whenever the page changes height; - calls
shouldStart3D(); if no,markFallback()and stop; - loads
popfold, the recipe and the beats, and callsstartScene({ canvas, homes, home, beats, getStage, reducedMotion, avatar: false, onStory, onPick }); - calls
markReady(canvas)andviewToggle().
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
- Scrub the story. Fix keyframes until each stop frames its room.
- Tick Pick in view, click pieces, nudge them, Save layout: each moved piece's line in
src/home.jsonchanges. Add a piece and Remove… put pieces on the list and take them off. - Check Evening light and the phone width.
- 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 checkfinds nothing wrong (one beat per.stagesection, in the same order). -
pnpm typecheckpasses. -
dist/index.htmlopened with?view=simpleshows a still and the stories in every section. -
dist/llms.txtreads 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.mdwith its creator and licence.popfold checkwarns about any model inpublic/models/thatCREDITS.mddoes 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.