Queek docs

Deploy your headless site

Put a site built on the Headless API on Vercel, Netlify or Cloudflare. Pick Server or Website connection by build type, set the keys on the host, use the production address, then go live from a dev store.

This page takes a site you built on the Headless API from your computer to the internet. It covers which connection to use, where the keys go on each host, what to add on Queek once the site has an address, and what to check before you tell the merchant it works.

Deploying with an AI tool?

The AI reads this page and Rules for AI builders. It never opens or prints a .env* file and never pipes a secret key into a host's command line. The merchant pastes secret keys into the host's settings page.

1. Pick the connection by build type

Your buildStarting pointConnection on QueekKey it usesWhere the key lives
Server-rendered: pages are built on a server (the Next.js starter, or any framework with server code)The Next.js starter. Fetch it with npx degit usequeek/developers/examples/nextjs-headless my-store.Server or backendSecret key (sk_…)The host's server environment only
Static or browser-only: the site is files, and the browser calls Queek (Vite, Lovable, Bolt, v0 exports)Your own buildWebsitePublic key (pk_…)In the browser bundle. It is safe there.
  • A Server connection lists no websites. A secret key needs no Origin, so a server render works from any address. See Authentication.
  • A Website connection only works from the exact https:// websites you list. See Websites allowed to use a key.
  • Server code that holds a Website key is refused with 403 origin_required. Use a Server connection for it (rule 7).

2. Pick a host

Each row below comes from the host's own documentation. The links are the pages read for this guide. Queek does not rank the hosts and does not run any of them: pick the one the merchant already has or prefers.

VercelNetlifyCloudflare
Server-rendered Next.jsImport the Git repository, or run the vercel command from the project folder. Pages that render on the server run as Vercel Functions.Connect the Git repository in the Netlify dashboard. Next.js runs through the open-source OpenNext adapter with no extra setup.Use the OpenNext adapter (@opennextjs/cloudflare) with the nodejs_compat flag enabled and a compatibility_date of 2024-09-23 or later.
Static buildImport the project from Git or run vercel. A single-page app needs a rewrite of every path to /index.html (Vite on Vercel).Git import, netlify deploy --dir=<output> --prod, or drag the output folder in (deploy a site).Point assets.directory at the build output and run wrangler deploy. A single-page app sets not_found_handling to single-page-application (static assets).
Where secrets and variables are setThe project's environment variables settings, per environment (Production, Preview, Development) (environment variables).Project configuration → Environment variables (get started).Workers & Pages → your Worker → Settings → Variables and Secrets for runtime, and Build variables and secrets when the host builds from Git (environment variables, OpenNext guide).
When a change appliesOnly to new deployments: redeploy (source).A new build and deploy is needed (source).In the dashboard, press Deploy to apply a change (source).
Build time or runtimeCode can read a variable during the build and while a Function runs. NEXT_PUBLIC_ values are written into the browser bundle at build time (source).Scopes Builds and Functions decide where a variable is visible. Scopes need a paid Netlify plan (source).Build variables are separate from the Worker's runtime variables (OpenNext guide).
Production addressThe project's production domain. Each deployment also gets its own generated URL, and branches and pull requests get preview URLs (environments).The site's main address (<site>.netlify.app or your own domain). Each deploy also has a permalink, and pull requests and branches have their own preview addresses (deploy overview).The Worker's address (<name>.<subdomain>.workers.dev) or a custom domain. Each uploaded version can have its own version URL (workers.dev, preview URLs).
Free tierHas a free Hobby plan (plan page).Has a free plan (plans).Workers has a Free plan (pricing).

Cloudflare and server-rendered Next.js

Cloudflare's own Next.js guide now points new apps at a different tool called vinext, and keeps the OpenNext adapter for apps that already use it. Queek has only checked the adapter's requirements (nodejs_compat, a recent compatibility_date) against Cloudflare's pages, and has not run the starter on Cloudflare. Treat Cloudflare for the server-rendered starter as untested, and read the adapter's page before you rely on it. A static build on Cloudflare uses the plain static assets path in the table.

Check the host's page for anything that changed since this guide was written. Hosts change their plans, limits and screens.

3. Set the environment variables

The merchant (or developer) sets these in the host's settings, not in the repository. The starter reads every one of them on the server only. None of them starts with NEXT_PUBLIC_.

VariablePublic or secretRequiredHolds
QUEEK_SECRET_KEYSecretYesThe secret key of a Server or backend connection: sk_live_… on a live store.
QUEEK_API_BASEPublicNoDefaults to https://client.usequeek.com/v1. Leave it unset.
QUEEK_WEBHOOK_SECRETSecretNoThe signing secret of the webhook endpoint in step 4. Without it, pages refresh on a timer.
QUEEK_STOREFRONT_PASSWORDSecretDev store onlyThe dev store's storefront password. For a build on your own computer. Never set it on a public site (step 5).

For a static build, the only Queek value is the public key (pk_…). It may sit in a variable your framework exposes to the browser, such as one that starts VITE_.

Keys and prefixes

A secret key (sk_…) never goes in a variable that starts with NEXT_PUBLIC_, VITE_ or EXPO_PUBLIC_. Those prefixes put the value into the browser bundle, where anyone can read it. Never put a secret key in git, a screenshot or a chat either.

How the secrets get there:

  1. The merchant opens the connection page (Channels → Headless API → your connection) and copies the secret key. It is shown once, when the connection is created or the key is replaced. Lost it? Press Replace secret key (Manage a connection).
  2. The merchant pastes it into .env.local for local runs, and into the host's environment settings for the deployed site.
  3. Set the variables for the environment the production site builds in, then redeploy so they apply.

An AI agent does none of these steps. It does not read .env*, print a variable, or send a secret to the host's command line (for example as an argument to a host CLI). It tells the merchant which variables to set and waits.

4. After the first deploy

The first deploy gives the site an address. Use the production address for everything below, never a preview address. A per-deploy address (a commit URL, a permalink, a version URL) changes with every deploy, and a branch or pull-request preview is a different address from the production site. Neither matches an exact allowed website, so the site's calls would be refused.

Allow the website (Website connections only)

Open the connection and add the production address under Websites allowed to use this key, for example https://shop.example.com. No path, no *. Or open a page on the deployed site once and press Allow on the Problems card for the blocked request, for a website you own. Details: Websites allowed to use a key.

A Server connection lists no websites, so skip this step.

Under After checkout, send customers back to, add https://<site>/thanks, using the production address. The starter's /thanks page only thanks the customer. A redirect is not proof of payment (rule 18). See After checkout, send customers back to.

Optional: refresh products when they change

So a price or stock change shows without a redeploy, the merchant creates a webhook endpoint in Settings → Notifications → Webhooks:

  • URL: https://<site>/api/queek-webhook
  • Topics: products/create, products/update, products/delete (optionally inventory_levels/update for stock-only changes and store/update for the store's name and logo)
  • Copy the signing secret shown there into QUEEK_WEBHOOK_SECRET on the host, then redeploy.

The starter's route verifies the signature and refreshes the cached product pages. Collections and blog posts have no topics, so they refresh on a timer. See Keep a headless site fresh.

Check it

The connection page changes from Waiting for your site… to Connected — first request … ago. A refusal appears on the Problems card with a one-click fix where one exists.

5. Dev store or live store

Dev storeLive store
Build and previewYes. On your own computer, with a Testing on my computer connection or a Server connection.After the plan is active.
Deploy to a public addressNever.Yes, with live keys.
NeedsNothing. Dev stores are free.An active paid website plan. Without one, every request answers 403 plan_inactive.

A dev store's storefront is password protected, and it can never be made public. If a deployed site held the password in its environment, anyone could reach the sandbox through that site. So a dev-store site stays on your computer. To run the starter against one, set QUEEK_STOREFRONT_PASSWORD locally. The server trades it at POST /auth/storefront/password for a token and sends it as X-Storefront-Token. See Dev stores.

To deploy:

  1. Finish and check the site on the dev store.
  2. Get live keys. Which way depends on the connection you built with:
    • Server or backend (the starter): on the live store, open Channels → Headless API → Connect a site or app, pick Server or backend, and copy the new sk_live_… secret key. A Server connection has no Go live button: it is a new connection on the live store.
    • Testing on my computer (a static build): press Go live on the testing connection, choose the live store and the type (usually Website, with the production address). Queek creates a new connection on the live store with live keys. See Go live from a dev store.
  3. The merchant puts the live key into the host's settings (QUEEK_SECRET_KEY for the starter) and leaves QUEEK_STOREFRONT_PASSWORD unset. Disconnect the dev-store connection when it is no longer needed.
  4. If the live store has no active plan, the deploy waits. The merchant upgrades the store's plan first.

Never complete a payment on a live store to test checkout. Check checkout up to Queek's hosted checkout page, and use a dev store's simulated payment page when you need to see an order finish.

6. Mind the request quota

A server-rendered site calls Queek from the host, so every visitor's page can count against one key. A Server connection's secret key has a request quota from the store's plan, and each key and IP has a shared per-minute ceiling. A 429 carries Retry-After. See Rate limits.

  • Cache reads. The starter caches catalogue reads and refreshes them on a timer or from the webhook above.
  • Send If-None-Match with the ETag you were given: an unchanged resource costs a 304.
  • Never call the API on every keystroke, and do not fetch the whole catalogue to render one page.

Pre-launch checklist

The checks from Rules for AI builders, plus the deploy steps:

  • GET /store/info returns the store's name, and the connection page reads Connected.
  • A product listing, a product page and a cart render from API data only.
  • Adding a line, validating the cart and pressing checkout lands on Queek's hosted checkout with that cart.
  • No secret key is in the code, the build output, the repository or a NEXT_PUBLIC_, VITE_ or EXPO_PUBLIC_ variable.
  • The only websites on the connection are exact https:// production addresses, with no *.
  • The deployed site uses the live connection's key, not a _test_ key, and no storefront password is set.
  • The live store has an active paid website plan.
  • https://<site>/thanks is under After checkout, send customers back to, and the page shows a thank-you and nothing more.
  • Nothing fulfils on a redirect. Queek runs fulfilment.
  • Reads are cached, and the optional webhook (if set up) shows delivered in Settings → Notifications → Webhooks.

On this page