Add Kicklace from Vercel

Written for two readers (#200). The first half is for a developer who presses Add Integration in Vercel; the second is the checklist only Michael can work through, because it lives in Vercel's Integrations Console and in an environment nobody else sets.

Michael, 2026-09-08: "developers can just click add integration inside Vercel to automatically inject all the API keys straight into their environment variables."

This is a different door from Releases from Vercel (docs/vercel.md), which is a webhook a customer registers by hand so their production deploys land as records. The two sit in the same frame on Settings → Integrations and each has its own Disconnect. The install can make the deployments webhook for you, which is the only place they touch.

---

For a developer

What one click does

1. You press Add Integration at https://vercel.com/integrations/<slug> and choose the team or the personal account it goes into.
2. Vercel opens Kicklace with a short-lived code. Kicklace swaps it for an access token straight away — a code lasts thirty minutes and signing in can take longer than that — and holds it, so the rest of this can wait for you.
3. You sign in to Kicklace, or sign up. You come back to exactly where you were.
4. One screen asks two things: which workspace (one you own or administer, or a new one) and which projects. Every project is ticked, and so is "Send deployments to Kicklace too".
5. Connect, and per project Kicklace:
   • mints a server key of its own, labelled Vercel: <project>;
   • writes four environment variables into the project, for production and preview;
   • allows the project's production addresses to post to your workspace, so the tag works;
   • and, once for the whole install, makes the deployment webhook so releases land too.
6. Redeploy each project once. Vercel gives a build the variables it had when the build started, so the one already running does not have them.

Nothing is emailed to anybody and nothing is charged.

The variables it writes

Both address variables are written because the package reads them separately: new Kicklace(…) reads KICKLACE_URL and <KicklaceTag /> reads NEXT_PUBLIC_KICKLACE_URL, and the package's own default is https://www.kicklace.com. A project connected to any other deployment needs both, or the tag posts somewhere else. docs/sdk.md and packages/kicklace/README.md are the package's own words.

They are written with Vercel's upsert, so a name your project already has is updated and never doubled. A variable you set by hand afterwards is the one that stands until you connect again.

Doing it twice

Pressing Connect again is safe, and is how you finish an install that stopped halfway:

• a project that already has its key keeps it — no second key is minted and KICKLACE_SECRET_KEY is not rewritten — and the public key and the address are refreshed;
• a project you tick for the first time gets everything;
• addresses already allowed are left alone;
• deployments are only connected once.

A step that fails says which project and why, and everything before it stays done. One Connect writes into at most twenty projects and stops after about forty-five seconds, saying where it got to; everything it wrote stands, and Connect again finishes the rest.

If you left "Send deployments to Kicklace too" unticked, or Vercel would not let Kicklace make the webhook that day, Connect deployments too under Connected from Vercel on Settings → Integrations does exactly the same thing later, with the same token. It is offered only while the deployments receiver has no secret, so it can never make a second webhook.

What is not written

• No key is ever shown on a screen, put in a log, or handed back in an answer.
• Kicklace never writes into a project you did not tick, and never touches a variable it does not own.
• Preview deployments get the key, so a preview branch reports as itself; development does not, because a developer's laptop should not be posting into a production workspace.

Taking it away

Two halves, and they are different:

• Disconnect on Settings → Integrations → Releases from Vercel → Connected from Vercel revokes the keys that install minted. They stop working at once. The variables stay in the projects, holding a key that no longer answers.
• Remove the integration in Vercel (Settings → Integrations → Kicklace → Remove) is what clears the variables: Vercel's own documentation says removing a configuration removes the webhooks, log drains and environment variables it made. Vercel then tells Kicklace, and Kicklace revokes the keys itself.

Either way the workspace, the people in it, the releases and the allowed addresses all stay. Taking a door away is not a reason to throw away what came through it.

While Kicklace is invitation-only

KICKLACE_SIGNUP decides whether a stranger may open a workspace (docs/signup.md). While it is at its default, a developer arriving from Vercel who is not in any workspace is told Kicklace is invitation-only and offered the waitlist; somebody who is already in one picks it and connects as normal. The install waits an hour, so starting it again from Vercel afterwards is one press.

---

For Michael: the checklist

Nothing below can be done by an agent. Three environment variables and one listing.

1. Make the integration

vercel.com → your team → Settings → Integrations → Integrations Console → Create.

A connectable account integration is the kind any team can make. It installs from https://vercel.com/integrations/<slug> as soon as it is created and carries the Community badge; the public marketplace listing comes after Vercel's own review and a few hundred installs. A native integration, billed through Vercel, is #84's question, not this one.

Fill in:

The Redirect URL has to be this deployment's own address, character for character: Vercel checks it again when the code is exchanged, and an install against a preview URL will not swap.

2. Tick the scopes

Nothing else. If Webhooks is not granted, the install still works and says one sentence: the customer registers the deployments webhook by hand, as docs/vercel.md describes.

3. Set the three variables

In Vercel → the kicklace project → Settings → Environment Variables, production (and preview, if you want an install flow to work against a preview deployment with its own Redirect URL):

All three or none. npm run env:check says which state the deployment is in, and with two of the three it fails outright, because a half-set integration is an install address that refuses every install.

Until all three are set: the install address answers with one honest sentence, /developers says nothing about Vercel installs, and Settings → Integrations carries only the deployments receiver.

4. The listing's assets

Vercel asks for these before the integration is public. They are all Michael's:

• a legal developer name — the entity behind Kicklace, as it should appear on the listing;
• a contact email — help@kicklace.com;
• Terms at https://kicklace.com/terms and a privacy policy at https://kicklace.com/privacy, both of which exist;
• a logo, square, at least 256×256, transparent PNG or SVG — the wordmark's mark on its own;
• screenshots, 16:9 — the install screen, Settings → Integrations, and a Releases board are the three that show what it does;
• a short description (one line) and a long description (a paragraph), in the site's own plain words: what a person gets, and what is written into their project.

5. Check it

1. npm run env:check — the line should read "Add Integration is on: developers install from …".
2. Open https://vercel.com/integrations/<slug> in a browser signed in to a Vercel account that is not yours, press Add Integration, and pick a throwaway project.
3. On the project: Settings → Environment Variables should show the four names, with KICKLACE_SECRET_KEY marked encrypted.
4. In Kicklace: Settings → Integrations → Connected from Vercel should name the team, the project and the day.
5. Settings → Your website should list the project's production address.
6. Remove the integration in Vercel, and the same frame should read "Removed in Vercel on …".

---

How it works, for whoever reads this next

• src/lib/integrations/vercel-install.ts — Vercel's API by plain fetch, with every page it was checked against cited in its header, plus the signed install cookie and the removal event's shape.
• src/lib/data/vercel-installs.ts — the vercel_installs table (migration 0033) and connectInstall, which is where the keys, the variables, the addresses and the webhook happen, step by step. The token is encrypted by src/lib/integrations/secrets.ts, like every other integration secret, and InstallState — what a screen is given — has no token and no key in it.
• src/app/integrations/vercel/install/route.ts — the Redirect URL. It swaps the code and does nothing else.
• src/app/integrations/vercel/install/finish/ — the one screen and its action.
• src/app/api/webhooks/vercel-integration/route.ts — the removal webhook, verified as HMAC-SHA1 of the raw body under the Client Secret.
• Tests: src/lib/integrations/__tests__/vercel-install.test.ts.