Quick start
Lock a Next.js site in about five minutes.
Use a patched Next.js
1. Create a site and a key
Make an account, add a site, and create a site key. The key looks like plk_ followed by two blocks of letters and numbers. It is shown once, so copy it straight into your host's environment settings:
PREVIEWLATCH_KEY=plk_...Keep it out of the browser. Do not prefix it with NEXT_PUBLIC_.
2. Install the package
npm install previewlatch3. Add the proxy file
In the root of your project (next to app, or inside src if you use one):
// proxy.ts (Next.js 16). On Next.js 14 and 15 the same code goes in middleware.ts.import { previewlatch } from "previewlatch/next";export default previewlatch();Next.js 16 calls this file proxy.ts. On Next.js 14 and 15 put the same code in middleware.ts.
Do not add a matcher
config.matcher, Next.js runs the gate on every request, including built JavaScript and CSS, images and files in public/. A matcher that skips some paths leaves those paths open. If something must be public, list it in publicPaths instead.4. Deploy and check
Deploy, then open the site in a private window. You should see a page that says "This site is private." with a password field. It does not show your site's name. Once you have a password (next step), use it there to see your site again.
If the key is missing or malformed, the site does not open up: every request gets a 503 with a "not set up" screen, and the server logs one clear error.
5. Invite people
In the dashboard, add a person and create a password for them. Choose reusable or one-time, and an expiry: none, 1 hour, 24 hours, 7 days, 30 days or a date. Copy it and send it to them. You will not see it again; if it is lost, revoke it and make a new one.
Options
All options are optional. Pass them to previewlatch():
import { previewlatch } from "previewlatch/next";export default previewlatch({ // Gate preview deployments on Vercel, leave production public. enabled: process.env.VERCEL_ENV !== "production", // A health check and a webhook that must stay reachable. publicPaths: ["/healthz", "/api/webhooks/*"],});| Option | Default | What it does |
|---|---|---|
key | process.env.PREVIEWLATCH_KEY | Your site key. Can hold two keys separated by a comma during a rotation. |
apiUrl | process.env.PREVIEWLATCH_API_URL, else https://previewlatch.com | Where the middleware checks passwords and sessions. |
enabled | true | Set to false to let requests through untouched, for example to gate previews but not production. |
publicPaths | none | Paths anyone may see without signing in. Exact paths, or a prefix ending in /*. |
offlineGraceSeconds | 86400 (24 hours) | How long a signed-in session keeps working while PreviewLatch cannot be reached. 0 locks people out on the first failed check. |
clientIp(request) | x-forwarded-for, else x-real-ip | How to read the visitor's address, used for per-address rate limits. |
sharedCacheHeaders | "auto" | Adds CDN-Cache-Control and Surrogate-Control: no-store to gated responses when not on Vercel. true always adds them, false never. |
next(request) | none | Your own middleware. It runs after the gate lets a request through. |
- Option
key- Default
- process.env.PREVIEWLATCH_KEY
- What it does
- Your site key. Can hold two keys separated by a comma during a rotation.
- Option
apiUrl- Default
- process.env.PREVIEWLATCH_API_URL, else https://previewlatch.com
- What it does
- Where the middleware checks passwords and sessions.
- Option
enabled- Default
- true
- What it does
- Set to false to let requests through untouched, for example to gate previews but not production.
- Option
publicPaths- Default
- none
- What it does
- Paths anyone may see without signing in. Exact paths, or a prefix ending in /*.
- Option
offlineGraceSeconds- Default
- 86400 (24 hours)
- What it does
- How long a signed-in session keeps working while PreviewLatch cannot be reached. 0 locks people out on the first failed check.
- Option
clientIp(request)- Default
- x-forwarded-for, else x-real-ip
- What it does
- How to read the visitor's address, used for per-address rate limits.
- Option
sharedCacheHeaders- Default
- "auto"
- What it does
- Adds CDN-Cache-Control and Surrogate-Control: no-store to gated responses when not on Vercel. true always adds them, false never.
- Option
next(request)- Default
- none
- What it does
- Your own middleware. It runs after the gate lets a request through.
Public paths
Matching uses the path as a standard URL parser reads it. A path containing an encoded slash or backslash, .., or a null byte is never treated as public, whatever you list.
The admin button (optional)
Add this line to your root layout and people with the admin role see a small "Manage access" button on the site that links to the dashboard. Everyone else gets an empty script.
<script src="/_previewlatch/overlay.js" async></script>The dashboard still asks for its own sign in. The admin role only decides who sees the button.