The install wizard
npx parlox init: the stacks it covers, every change shown as a diff first, and how to undo it.
On this page
The install wizard adds both parts of Parlox to a Next.js, Vite React, Express or Hono project, or to a repository that holds a frontend and a backend: one command, one diff to confirm.
npx parlox initIt is the npm package parlox, published from the public repository with provenance like the SDKs. Run it at the root of your project, with a clean git working tree.
What it installs
| Stack | Browser part | Server part |
|---|---|---|
| Next.js 13 and later | <ParloxAnalytics /> in the root layout or _app | withParlox() in middleware.ts or proxy.ts |
| Vite React | <ParloxAnalytics /> beside <App /> in the entry file | On Vercel, a middleware.ts (Routing Middleware), added only when the wizard can prove your build cannot put the key into browser code. Elsewhere none: a static site has no server |
| Express 4 and 5 | The pinned tag in each view with a <head> (EJS, Handlebars, Mustache, Nunjucks, Eta, Liquid, Pug, Jade) or static .html page, up to 20 pages | app.use(parlox()) right after const app = express() |
| Hono (Node, Bun, Cloudflare Workers and Pages, Vercel, AWS Lambda) | The pinned tag in your JSX layout or html template | app.use(parlox()) right after new Hono() |
A folder with a Vite frontend served by its own Express or Hono server gets both: the component in the Vite entry, the middleware in the server file. In a monorepo it lists the apps it found and asks which to include; one diff and one confirmation cover them all.
The packages go in at exact, tested versions: @parlox/browser@1.0.3 and @parlox/server@1.2.0 (and, for Vite on Vercel, Vercel's own @vercel/functions if the project lacks it). The wizard never replaces a newer Parlox package your project already lists.
What it does, in order
- Reads your project, without writing anything: each app's stack, entry or server file, TypeScript, module system, package manager, and whether the app loads a
.envfile. - Signs you in in your browser (OAuth with PKCE, on a loopback port on your machine).
- Asks which site this project is, or creates one.
--site <domain>picks it without asking. - Shows the diff of every change, and the commands it would run, before touching anything.
- Applies it once you agree, and runs your package manager to add the packages.
- Connects your host. On a linked Vercel project (with you signed in to the Vercel CLI) it asks, then creates a key and sets
PARLOX_SECRET_KEYandPARLOX_VERIFY_TOKENthroughvercel env add. The key is stored as a Secret where your Vercel CLI supports it, otherwise as Sensitive: no one can read it back from Vercel, and your deployments and builds still receive it. Anywhere else it opens the dashboard's key form with the key's name filled in, and shows the two variables and where they go on that host. - Offers a local check where the app loads its token locally: with your dev server running, it asks it for
/.well-known/parlox-verify. - Reports what happened, each line labelled with how it knows: "added to your code", "verified locally", "confirmed after you deploy", "not checked", and what your stack does not cover and why.
The key it creates
Every key the wizard creates has access "Crawler reports only": it can send reports of automated requests and nothing else. No orders, no reading your stats. A host's build can often read the server's variables, and this bounds what a leak there can do: at worst, made-up crawler visits on one site until you revoke the key.
Orders need a send key of their own, which you create in the dashboard: Purchases from the server.
Files it changes
- The browser part and the server part, as in the table.
- An env file, only where your app already loads one (
.env.localon Next.js; the.envyour Express or Hono app loads). It writesPARLOX_VERIFY_TOKENthere, which is not a secret, and never your production key. A file git tracks, or one that is a link, is left alone; you get the line to add by hand. .gitignore, to ignore that env file if git does not already.public/.well-known/parlox-verifyfor a Vite site without the middleware, so the domain can still be verified.package.jsonand your lockfile, through your own package manager.
Every edit keeps your file's formatting, quotes, semicolons and comments, at a place the file's syntax tree says is right; only an env file is rewritten line by line. Where a file cannot be edited safely, the wizard shows the exact snippet to paste and where, instead of guessing.
What it never does
- Never stores a secret key on your machine, unless you ask for a local one with
--local-key(a separate "Crawler reports only" key in your app's env file). - Never shows what else is in your env file: the diff shows the
PARLOX_VERIFY_TOKENline, and every other line only as a stand-in. - No telemetry and no AI: the edits are fixed templates, shown as a diff first. Your code is never sent anywhere. The only details of your project or machine it sends are in the names of the keys it creates: an app's folder, in a run with several apps, and your computer's name, with
--local-key. - Never starts your app, never adds a loader such as
dotenv, and never replaces your existing middleware: it wraps it, or shows a snippet. - Talks only to
gateway.parlox.io, Parlox's sign-in service (hosted on Supabase), your own dev server onlocalhostfor the local check, your package manager, and, on a linked Vercel project, your ownvercelCLI. - Refuses to write outside your project folder or through a symlink.
Useful flags
| Flag | Effect |
|---|---|
--dry-run | Show the plan and the diff; write nothing, install nothing, create no site or key |
--yes | Accept the diff and the install without asking (required without a terminal, as in CI) |
--site <domain> | Use the site with this domain |
--app <folder> | Include this app of a monorepo (repeatable) |
--plain | A plain, line-by-line session instead of the full-screen app |
--no-vercel | Skip the Vercel step and print the variables to set by hand |
--local-key | Also write a separate "Crawler reports only" key to the app's env file, for your dev server |
--allow-dirty, --allow-no-git | Continue with uncommitted changes, or outside a git repository |
The full list is in the wizard's README.
Uninstall
npx parlox uninstallIt shows a diff, then takes out exactly what it added: the component, the middleware line and its import (or the whole middleware file if the wizard created it), the tags it wrote (only those after its parlox:wizard marker comment, never a tag you pasted), the ownership file, the PARLOX_VERIFY_TOKEN line and the Parlox packages. @parlox/server stays while a file of your own still imports it, such as your purchase() code. A PARLOX_SECRET_KEY line stays too, since the wizard cannot tell its local key from yours.
It revokes no key: do that in the dashboard (Settings → Keys).
Not covered yet
- Shopify, WordPress and WooCommerce: use the pinned tag.
- Vue or Svelte on plain Vite, Nuxt, SvelteKit, Astro, Remix, React Router 7 in framework mode, TanStack Start, NestJS and others: install the npm package and the server part by hand. The wizard says so and points to the guide.
- Static sites off Vercel: the browser part only, since there is no server to report crawlers.