@popcraft/runtime

The code projects exported from PopCraft share. An exported Next.js project is plain React first; what has to be common code lives here, versioned, and is the same code PopCraft itself runs.

You do not install this by hand: an exported project's package.json asks for it.

What is in it

| Import | What it is | | --- | --- | | @popcraft/runtime | What an expression means (ops, truthy, num, exprText, FUNCTIONS); the players for a prototype (popcraftMount) and a state machine (popcraftMachine); the page controls (switchMode, controlTimeline, scrubTimeline, orbitDrag); the site contract (endpoints, sign-in and record rules); and createSiteClient, what a page asks of its site's server | | @popcraft/runtime/commerce | What storefront components bind to: Next.js Commerce's types (Product, Cart, CartItem, Collection, Menu), the fields a design reads for each (COMMERCE_FIELDS), commerceItem to flatten one into them, formatMoney, and the storefront form actions | | @popcraft/runtime/server | For Node: siteRequest, which answers a site's own requests (forms, sign-in, each visitor's records); the Neon Auth relay; neonStore, a site's forms and records in its own Postgres database |

An exported project with forms or accounts answers /_pc/… in one route handler:

import { siteRequest } from '@popcraft/runtime/server'
import { site } from '@/lib/popcraft-server'

async function handle(request: Request, { params }: { params: Promise<{ path: string[] }> }) {
  const { path } = await params
  return (await siteRequest(request, `_pc/${path.join('/')}`, site)) ?? Response.json({ error: 'Not found' }, { status: 404 })
}

export { handle as DELETE, handle as GET, handle as POST }

Examples

In getpopcraft/examples: a digest worked out with an exported app's expressions, and an exported site's forms answered from a plain Node server with a JSON-file SiteDatabase in place of Neon.

Versions

Semantic versioning. A change an exported project would notice (a function's result, a removed export) is a new major; an exported project asks for ^ the version it was exported with, so it takes fixes and never a breaking change. Release notes: CHANGELOG.md.