PopCraft Docs

Export as web code… → Website (Next.js project) turns every screen of a page into a Next.js app written the way a Next.js team writes one today. Pick Next.js project with Tailwind for the same project styled with Tailwind CSS classes.

Export a Next.js project, then run it · 0:09

Description

The website template on the canvas. The web export is opened and Website (Next.js project) is picked; Export downloads a zip. The zip is unzipped, its packages installed and the project built and started with Next.js, outside PopCraft: the landing page appears at the site's root, and its Pricing link opens the pricing page at /pricing.

What is in the zip

Path	What it is
`app/layout.tsx`	The page around every route: language, fonts through `next/font`, the site's metadata (title template, Open Graph) and viewport
`app/page.tsx`, `app/pricing/page.tsx`, …	A route per screen, at the address you gave it (Web › Page): its title, description and canonical address as typed `Metadata`, and the screen it renders
`app/**/screen.tsx`	The screen as plain TSX: real elements with their styles, links as links, form controls, motion as CSS keyframes
`app/not-found.tsx`	The 404 screen, when the page has one
`app/globals.css`	The file's variables (and their modes), the breakpoints as media queries, and Tailwind when you picked it
`app/sitemap.ts`, `app/robots.ts`	`/sitemap.xml` with every route and `/robots.txt`, made from `NEXT_PUBLIC_SITE_URL`
`lib/popcraft.tsx`	The design's variables as React state every page shares, the overlays it opens, and (with forms or accounts) who is signed in
`components/overlays.tsx`	The frames the design opens as overlays, when it has any
`app/api/popcraft/`, `lib/popcraft-server.ts`, `proxy.ts`	The site's own server, when it has forms, accounts or each visitor's own lists: see Forms, accounts and data
`components/gpu-island.tsx`, `public/pc/`	Layers only the GPU can draw (a shader, a 3D scene), drawn live: see GPU layers
`components/code/`	The file's code components, as their source
`public/`	The pictures, including any the design takes from PopCraft (a template's placeholder logo)
`next.config.ts`, `eslint.config.mjs`, `tsconfig.json`	Next.js, ESLint (Next.js's recommended rules) and strict TypeScript, set up
`.env.example`, `.gitignore`, `README.md`	What to set, what not to commit, and how to run it

Run it

You need Node.js 20.9 or newer.

npm install
npm run dev

Then open http://localhost:3000. The project's README lists every command: npm run build, npm start, npm run lint and npm run typecheck.

How it is written

Server first. Each page.tsx is a server component that says its metadata. A screen that has to run in the browser (motion waiting for a click, a prototype) is a client component in screen.tsx beside it, so the page keeps its title and description either way.
Fonts through next/font. Google fonts are downloaded at build time and served from the site itself, with no request to Google from a visitor's browser and no layout shift.
Pictures through next/image. Each is served at the size its screen needs, as AVIF or WebP where the browser takes it.
Current packages. Next.js, React, TypeScript, ESLint and Tailwind CSS are pinned to the versions PopCraft last built exported projects with; they are checked against npm every week, and a version only reaches an export once sample projects install, lint, type-check and build with it.

What the design does

What you built in Prototype comes with the project, written as React a developer can read and change:

Variables are React state every page shares. Layers bound to a variable or an expression (words, visibility, size, opacity, rotation, corners) follow it.
Actions: go to a page, back, open a link, scroll to a layer, set a variable, if/else, open, swap and close an overlay, change a component's variant, switch a variable mode (a theme), and play, pause or seek a timeline. A click, hover, press, delay or key starts them, as in the design. Anything clickable is a button to a keyboard and a screen reader too.
Drags that turn a 3D layer or scrub a timeline.
State machines play through the same player PopCraft uses.

What an expression means (its operators and functions) and the players come from @popcraft/runtime, a small package PopCraft publishes, so a value is the same in PopCraft, on a published site and in the export. Everything else is plain React and Next.js.

Forms, accounts and data

A page with forms, sign-in or lists each visitor keeps (Collections › Each visitor has their own) gets a server of its own: app/api/popcraft answers the pages, through @popcraft/runtime/server, which is the code PopCraft's own hosting answers a published site with. To host an export somewhere else, the same handler runs in any Node server: an exported site's forms on a plain Node server, with its submissions in a JSON file.

Forms are kept in the site's database.
Sign-up, sign-in, sign-out, changing a name or password, a forgotten password and deleting an account go through Neon Auth. The session is a first-party cookie the page's script never sees.
Each visitor's own lists show their records, newest first; a form adds one, and one inside a list's copy changes or removes that copy's. Expressions like count("Checkins") or streak("Checkins") count their records.
Pages for one kind of visitor (Page › Who it is for): proxy.ts sends a visitor who is not signed in from a signed-in page to the sign-in page, and the other way round.

Set these in .env.local (and on your host):

Variable	What it is
`DATABASE_URL`	A Postgres connection string, such as a Neon project's. The site makes its two tables on first use
`NEON_AUTH_URL`	The Neon project's Auth URL (Neon console → Auth), for sites with accounts. Add the site's address to its trusted domains
`NEXT_PUBLIC_SITE_URL`	The site's address

Without DATABASE_URL the pages still work: forms are sent and not kept, and nobody can sign in.

GPU layers

A layer CSS has no word for and that moves (a shader that reads the time, a 3D scene, a video in a shape) is drawn by the renderer PopCraft draws it with. The project carries that renderer in public/pc/island.js, with what each layer draws in public/pc/islands.json. A page asks for them only once such a layer is on screen. Until then, and in a browser without WebGPU, the layer's picture shows.

Transitions between screens are not part of the project: links go straight to the next page. A published site, the web preview and the static export play them, 3D transitions included.

Deploy

Copy .env.example to .env.local and set NEXT_PUBLIC_SITE_URL to the site's address, then deploy anywhere that runs Next.js: Vercel, a Node.js server (npm run build && npm start) or a container. To deploy from PopCraft itself, connect GitHub or Vercel (Integrations).

Exporting again

Exporting again writes the files again. Keep changes you want to survive in files of your own, or treat the project as yours from then on and stop exporting.