PopCraft Docs

With a Supabase account connected, a site published on PopCraft's hosting keeps what its forms are sent, and its visitors' accounts, in a Supabase project of yours. It works like Neon: the site, its forms and its pages are the same; only where the data lives changes.

Give the site a database

Give a site a Supabase database in one click, then read what the form was sent · 0:08

Description

The coming-soon page, published, with its email sign-up marked as a form and a Supabase account connected. In the Publish dialog, under Database, New Supabase database is clicked: a project named after the site is made in the Supabase organization and attached, and it is listed. Three visitors then sign up on the site (sent by the recording, as the site sends them). Submissions is clicked and a table shows the three, newest first, with when each was sent and its email.

Publish the site.
In the Publish dialog, under Database, click New Supabase database. A project named after the site is made in your organization and attached. A new project takes a minute or two to start: the button says Making it… until it is ready.
To use a project you have, type in the field below the buttons and pick it.

No Supabase account connected yet? Connect Supabase connects it and then makes the project, in the same click. A site with accounts gets sign-in turned on with it.

From then on, every form on the site saves what it is sent. Nothing needs republishing.

Read what was sent

Click Submissions beside the database. Each row is one submission: when, which form, and the fields as sent. You can also query them in Supabase's SQL editor:

SELECT created_at, data->>'email' AS email FROM popcraft_site_xxxxxxxxxx.popcraft_submissions ORDER BY created_at DESC;

(The schema's name is the role's; it is listed under Database → Schemas.)

The templates with working forms and complete apps (Daybreak, Wayfarer, Potluck and the rest) work with Supabase as they do with Neon: see Templates to start from.

One account, many projects

A connection is the account; it reaches every organization the token's user belongs to. Each file picks its own project, and several files can share one project: each gets a role and schema of its own, so their data stays apart.

What PopCraft does in your project


Creates	A role and a schema of the site's own (`popcraft_site_…`), and in that schema the tables `popcraft_submissions` and `popcraft_records`. They stay out of `public`, so Supabase's REST API does not serve them.
Writes	One row per form sent; each signed-in visitor's own records.
Reads	Those tables, when you open Submissions and when a signed-in visitor opens their lists.
Keeps	The role's connection string (through Supabase's transaction pooler), encrypted. With sign-in, the project's anon and service keys, encrypted. None is ever shown or returned.
Leaves alone	Everything else in the project.

A new project is made in us-east-1 unless your PopCraft server sets another region. It counts toward your Supabase plan (the free plan allows two active projects).

What a visitor can do

The same as with Neon: forms are accepted only from the site's own pages, for forms it has, within size and rate limits, and stored as data, never run as SQL. See What a visitor can do.

Turn on Visitors can sign in (a file built with sign-in forms turns it on when the database is attached). PopCraft adds your site's address to the project's Auth redirect URLs and keeps its keys on the server. Visitors' accounts are Supabase Auth users of the project (Authentication → Users).

If the project confirms email addresses (Supabase's default), a new visitor confirms theirs before they can sign in; the site tells them to check their email. Turn confirmation off under Authentication → Providers → Email.
Reset emails are sent by Supabase and open your site's /reset-password page. Change their wording under Authentication → Email Templates.
A visitor deleting their account deletes their Supabase Auth user and what the site kept for them.
A visitor's session lasts as Supabase says, and is renewed while they use the site.

Everything else about sign-in (forms, pages for signed-in visitors, each visitor's own lists, lists everyone shares) is described on the Neon page.

Detach

Click Detach. The site stops saving. The role, schema and rows stay in your project.

Ask the AI agent

Save this form's answers in my Supabase.

The agent checks what is connected, makes a project named after the site when you have none in mind (or lists your projects and asks which), and asks you to approve before it creates or attaches anything.

Tool	What it does
`list_integration_resources`	The organizations, then the projects, of a connected account.
`attach_database`	Attach a project, or make one (`create: true`, or `createNamed` in an organization). Asks first.
`set_site_sign_in`	Turn visitor sign-in on or off. Asks first.
`get_form_submissions`	What visitors sent, newest first.

Command line and API

curl -X PUT -H "Authorization: Bearer $POPCRAFT_TOKEN" -H "content-type: application/json" \
  -d '{"create": true, "provider": "supabase"}' https://popcraft.app/api/v1/files/KEY/site/database

popcraft run --ui integration.submissions --json

The token needs the sites:publish scope to attach, files:read to read. The endpoints are in the reference.

Export it

An exported Next.js project keeps its data in Supabase too. Set DATABASE_URL to the project's connection string (Connect → Transaction pooler), and with sign-in SITE_AUTH_KIND=supabase-auth, SITE_AUTH_URL=https://<project>.supabase.co/auth/v1 and SITE_AUTH_KEY (the anon key); SITE_AUTH_ADMIN_KEY, the service key, lets visitors delete their accounts. Deployed to a Vercel project that is a destination, these are set for you.

When something goes wrong

What you see	What to do
Making it… for a long time	A new project takes a minute or two. After about two and a half minutes PopCraft stops waiting: try again, and it uses the project once it is up.
That Supabase project is paused	Free projects pause after a week unused. Restore it in the Supabase dashboard.
A new project is refused	The free plan allows two active projects. Pause or delete one, or pick a project you have.
A visitor never gets the confirmation email	Supabase's built-in mailer sends only a few emails an hour. Set up your own SMTP under Authentication → Emails, or turn confirmation off.
This site's sign-in does not offer that on deleting an account	The service key was not available when sign-in was turned on. Turn sign-in off and on again.

Not yet

Signing in with Google, GitHub or other Supabase Auth providers.
Lists everyone sees that read from the database.