Mist app starter template

Every Mist app starts as a copy of Fluid’s public starter template, Fluid-WeCommerce/mist-next-app-template on GitHub. When you create an app, Fluid generates your app’s private repository from it. Your repository is a one-time copy. Changes to the template after you create an app don’t reach it. To pull in a later template change, add the template as a Git remote and cherry-pick the commits you want.

What’s in it

The template is a Next.js app written in TypeScript. It uses Drizzle to talk to Postgres and Vitest for tests.

Path	What it does
`app/page.tsx`	The landing page of a new app. Replace it with your own.
`app/api/health/route.ts`	`GET /api/health` runs a test query and returns `{"db":"ok"}`, or a `503` when the database isn’t reachable.
`app/api/webhooks/route.ts`	Receives webhooks from Fluid, verifies their signatures and routes each event to a handler. `/api/webhooks/installed` and `/api/webhooks/uninstalled` are aliases for the droplet lifecycle events.
`app/embed/checkout-banner/page.tsx`	A working example page for a drop zone above fast checkout.
`app/embed/session-example/route.ts`	A working example that verifies who is viewing an embedded page.
`lib/config/droplet.config.ts`	The webhooks, callbacks and drop zones your app registers when a company installs it.
`lib/handlers/`	The handlers for each webhook event.
`lib/fluid/`	The Fluid API client, installation context and session token helpers.
`lib/db.ts`	The database client.
`lib/schema.ts` and `lib/ensure-schema.ts`	The database tables and the code that creates them on first use.
`proxy.ts`	Sets headers so only Fluid can frame the app’s pages.
`scripts/register-lifecycle-webhooks.mjs`	Points a droplet’s install and uninstall webhooks at your app.

Scripts

Command	What it does
`npm run dev`	Runs the app locally on `http://localhost:3000`, with a local database.
`npm run build`	Builds the app for production.
`npm run typecheck`	Checks types.
`npm run lint`	Lints the code.
`npm test`	Runs the tests.
`npm run register:webhooks`	Registers the droplet’s lifecycle webhook URLs. See Integration points.

The template pins Node 22 in .tool-versions.

Local and production databases

The same code runs against two different databases:

Locally, npm run dev uses an embedded Postgres that runs inside Node and saves to a local.db folder in your project. You don’t need to install Postgres. The folder is in .gitignore.
In production, the app connects to its own hosted Postgres database through DATABASE_URL, which Fluid sets for you.

lib/db.ts picks the database for you, and both return the same Drizzle client. Your queries don’t change between the two. Data you create locally never reaches production.

Add a table

The template doesn’t run a migration step. Instead, ensureSchema() in lib/ensure-schema.ts runs CREATE TABLE IF NOT EXISTS statements the first time the app needs the database.

Define the table

Add the table to lib/schema.ts with Drizzle’s pgTable.

Create it on first use

Add a matching CREATE TABLE IF NOT EXISTS statement to ensureSchema().

Call ensureSchema first

Call await ensureSchema() before your route’s first query.

For a larger app, switch to real migrations, such as drizzle-kit, rather than growing ensure-schema.ts. The template creates two tables of its own: companies, with one row per installation of your droplet, and webhooks, an audit log of every webhook the app receives. Keep them.

Extend the app

Handle a webhook event

Write the handler

Add a file under lib/handlers/, such as order-created.ts, that exports an async function.

In lib/handlers/index.ts, add registerHandler("order.created", handleOrderCreated).

Turn on the webhook

In lib/config/droplet.config.ts, set enabled: true on the matching webhook entry.

Declare what your app registers

lib/config/droplet.config.ts lists everything your app registers with a company when the company installs it. Every entry ships with enabled: false. Turn one on only once the route behind it exists.

lib/config/droplet.config.ts

dropzones: [
  {
    enabled: true,
    uuid: "mist-checkout-banner",
    name: "Checkout Banner",
    page: "checkout",
    zone: "above_fast_checkout",
    embedPath: "/embed/checkout-banner",
    description: "Example banner rendered above fast checkout",
  },
],

Section	What each entry registers
`webhooks`	A company webhook for one `resource` and `event`, such as `order` and `created`.
`callbacks`	A callback registration. `definition_name` must match a callback definition in Fluid. See Callbacks.
`dropzones`	A drop zone that renders `embedPath` from your app in a `page` and `zone`.

On install, the app registers each enabled entry for that company and saves the IDs. On uninstall, it removes them.

Get started

Mist apps

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Mist app starter template

What’s in it

Scripts

Local and production databases

Add a table

Extend the app

Handle a webhook event

Declare what your app registers

​What’s in it

​Scripts

​Local and production databases

​Add a table

​Extend the app

​Handle a webhook event

​Declare what your app registers

​Related pages

What’s in it

Scripts

Local and production databases

Add a table

Extend the app

Handle a webhook event

Declare what your app registers

Related pages