Skip to content

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:

.env
PREVIEWLATCH_KEY=plk_...

Keep it out of the browser. Do not prefix it with NEXT_PUBLIC_.

2. Install the package

Terminal
npm install previewlatch

3. Add the proxy file

In the root of your project (next to app, or inside src if you use one):

proxy.ts
// 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

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():

proxy.ts
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/*"],});
previewlatch() options
OptionDefaultWhat it does
keyprocess.env.PREVIEWLATCH_KEYYour site key. Can hold two keys separated by a comma during a rotation.
apiUrlprocess.env.PREVIEWLATCH_API_URL, else https://previewlatch.comWhere the middleware checks passwords and sessions.
enabledtrueSet to false to let requests through untouched, for example to gate previews but not production.
publicPathsnonePaths anyone may see without signing in. Exact paths, or a prefix ending in /*.
offlineGraceSeconds86400 (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-ipHow 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)noneYour 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.

app/layout.tsx
<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.