How we got the Next.js integration down to one command
A look at how RankFirst moved the Next.js setup from a checklist into one calm flow: run npx, approve the site, keep shipping.
The flow
One command. One approval. One repo that is ready to go.
1 · terminal
Start in the repo
The integration starts where the work already lives. No dashboard detour first.
2 · browser
Approve the site
Instead of copying keys out of a settings screen, you pick the site once and let the flow finish.
Link this repo
Signed in as the current account
3 · repo
Ship with the right pieces in place
Generated routes, env vars, webhook, and sitemap support land together so the repo feels finished.
The old version still worked. It just asked too much.
The adapter was solid. The docs were clear. None of that fixed the part that actually slows people down: too many tiny decisions up front. Generate a key. Copy the secret. Paste the webhook URL. Add the env vars. Build the route files. Hope nothing drifted.
That kind of setup is survivable once. It gets old fast when you are trying to evaluate a tool in the middle of a real workday. So we stopped treating integration as documentation and started treating it as product surface area.
Now the setup starts where developers already are.
Inside a Next.js App Router repo, the entry point is just `npx rankfirst`. The CLI checks the project, asks where posts should live, writes the integration files, patches `next.config.*`, and prepares the env scaffolding.
That already cuts out a lot of friction. The bigger change is what happens next: instead of making you hunt for keys in another tab, the CLI can open RankFirst in the browser, use the account you are already signed into, let you pick a site, then write the API key and webhook secret straight into `.env.local`.
The browser step matters because it removes the worst part.
Copy and paste sounds small until you count how many ways it goes wrong. Wrong site. Old key. Missing webhook. Secret pasted into the wrong file. The browser approval flow gets rid of that entire class of mistakes.
You choose the site once, the server rotates the API key, sets the webhook to `/api/rankfirst/revalidate`, and sends the credentials back to the local CLI callback. The repo ends up configured, not half-configured.
We also wanted the generated app to fail gracefully.
The generated blog routes use the resilient client and snapshot cache, so a build can still complete if RankFirst is briefly unavailable. That part stayed important. Smooth setup is nice, but smooth setup followed by brittle builds is still a bad product.
The result is a flow that feels lighter in the first five minutes without throwing away the practical stuff later: sitemap wiring, revalidation, image config, server-only auth, and a sane article renderer are still there.
The best test was boring.
After publishing both packages, we tested the public path the same way a stranger would: fresh `create-next-app`, `npx rankfirst`, install the adapter, build, run, open `/blog`, open `sitemap.xml`.
That kind of test is unglamorous, which is exactly why it matters. If the integration feels obvious from a cold start, we did the job right. If you need a support call to get through setup, we did not.
Under the hood
The simple version still does the important work.
Revalidation wired in
The generated route handles the signed webhook so newly published content can invalidate caches immediately.
Env stays local
The link flow writes the live credentials into `.env.local`, which keeps secrets out of the browser and out of the docs dance.
Resilient by default
The generated helper uses the resilient client and snapshot cache so a temporary API wobble does not automatically nuke the build.
Next-native routes
You still end up with plain route files in your repo, which means the result is readable and reviewable instead of hidden behind a black box.