Skip to content

Documentation

Start from the starter

A Next.js project with Kicklace already wired in.

Press the Deploy Button and Vercel copies the starter into your own GitHub account, asks for your keys, and builds it. You have a site recording visitors, storing what each person agreed to, and posting purchases before you have written a line. It's your repository from that moment, not a template you're locked into.

Beside it, npx kicklace init adds the same wiring to a Next.js project you already have. One command, four changes, all of which it shows you first.

The starter lives in a public repository of its own, and the button clones it from there. /developers shows the button and names the command once this deployment has been pointed at that repository; the wiring below is the same either way.

The Deploy Button's address

The button is a link to vercel.com/new/clone with the repository and the variables to ask for. This is the whole address:

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FKicklace%2Fkicklace-nextjs-starter&project-name=kicklace-starter&repository-name=kicklace-starter&env=KICKLACE_SECRET_KEY,NEXT_PUBLIC_KICKLACE_KEY,KICKLACE_URL,NEXT_PUBLIC_KICKLACE_URL&envDefaults=%7B%22KICKLACE_URL%22%3A%22https%3A%2F%2Fwww.kicklace.com%22%2C%22NEXT_PUBLIC_KICKLACE_URL%22%3A%22https%3A%2F%2Fwww.kicklace.com%22%7D&envDescription=Your%20Kicklace%20keys%2C%20from%20Connections%20%E2%86%92%20Your%20website%20%E2%86%92%20For%20your%20developers%3A%20the%20public%20key%20for%20the%20tag%2C%20and%20a%20secret%20key%20for%20your%20server.&envLink=https%3A%2F%2Fgithub.com%2FKicklace%2Fkicklace-nextjs-starter%23environment-variables

Every parameter, and where Vercel documents it:

Parameter What it does Source
repository-url the template to clone vercel.com/docs/deploy-button/source
project-name, repository-name what the new project and repository are called by default the same page
env a comma-separated list of names the deploy form asks for, and requires vercel.com/docs/deploy-button/environment-variables
envDefaults a URI-encoded JSON object of default values, for names that are not secret the same page
envDescription one sentence shown beside the fields the same page
envLink where to read about them; the docs ask for a specific page, not a top-level one the same page

The four names are the same four the Vercel install writes into a project, for the same reason: <KicklaceTag /> reads NEXT_PUBLIC_KICKLACE_URL, and the package's own default is www.kicklace.com, so a project pointed anywhere else needs both addresses.

Only the two addresses get an envDefaults value. A default is for a public endpoint and never for a key: nobody's key is ever in a URL, because the address ends up in the browser's history.

STRIPE_WEBHOOK_SECRET is deliberately not in env. The starter's Stripe route is optional, and requiring a secret at deploy time for a route you may never use would stop the deploy. .env.example names it and the route says what happens without it.

There's no vercel.json in the starter. Vercel detects Next.js on its own.

What is in the starter

File What it shows
app/layout.tsx <KicklaceTag />, reading the two public variables
app/consent.ts the list and the consent sentence, as one constant the form and the handler share
app/signup-form.tsx the form, and the browser id the tag keeps (kl_id) going with the post
app/api/signup/route.ts identify, then subscribe with that sentence
app/api/webhooks/stripe/route.ts the signature by node:crypto, then track("purchase", …) with an idempotency key
app/kicklace.ts one client, built per request so a project with no key still builds

The Stripe route opens by saying that Kicklace takes Stripe's webhook itself (Payments from Stripe), that it's the better path, and that running both would land the purchase twice.

Proving it builds

The starter is a whole Next.js app, so it builds the way any of them does:

npm install
npm run build          # ✓ Compiled successfully, four routes

No lockfile is committed with it, the way Vercel's own examples do it. It also builds with no keys set: app/kicklace.ts makes its client per request, so a project with nothing filled in still compiles.

npx kicklace init instead

For a Next.js project that already exists. It finds the nearest package.json, refuses anything with no next in it, then adds the import and <KicklaceTag /> inside <body> of your layout, adds kicklace to dependencies, and appends the four variable names to .env.example. It never overwrites a value you set, writes nothing until every step can be done, and --dry-run prints every change and makes none. The kicklace package has the rest.