Preview environments with isolated data
A preview environment should be a disposable deployment with its own data and integration boundaries. Use synthetic fixtures, separate credentials and callbacks, and a stable environment identity that survives retries. Verify public build-time configuration and clean up resources even when the pull request closes unexpectedly.
Inside this article 6 sections +
A preview URL is only the visible edge of an environment. Behind it may be a database, object bucket, queue, authentication callback, email provider, and background worker. If those resources still point at production, a convincing preview can perform real business actions while appearing temporary.
Design the preview as a complete lifecycle: allocate, seed, deploy, exercise, update, and destroy. Use an environment identity that ties every resource and callback to the same temporary deployment. A branch name alone is often insufficient because branches can be renamed, reused, or contain characters unsuitable for resource names.
Give the preview a stable resource identity
Derive a sanitized identifier from the repository and pull-request or preview record, then store the mapping to deployment revisions. Repeated workflow attempts should update the same intended preview rather than create unrelated resources indefinitely. A new commit can have a new application revision while retaining the environment's ownership record.
Tag or name provisioned resources with that identity and an expiry policy. Record the database or schema, queue namespace, object prefix, callback route, and credentials reference in one environment manifest. This gives cleanup a concrete inventory and helps operators investigate resources left behind by an interrupted workflow.
- Application
- Preview identity, source revision, and visible non-production label.
- Data
- Synthetic tenant, isolated schema or database, and scoped object storage.
- Background work
- Preview-specific queue routing and worker credentials.
- External services
- Sandbox accounts, safe callback URLs, and disabled irreversible effects.
- Cleanup
- Inventory, expiry, owner, and repeat-safe deletion procedure.
Seed useful synthetic data
Create fixtures that cover realistic product states: multiple roles, an empty account, a large list, an expired invitation, and a recoverable failure. Synthetic data should be deterministic enough for reviewers and browser tests to find the same scenario. A preview full of random records can be visually rich but operationally difficult to review.
Do not copy production customer data merely to make the screen look authentic. If a sanitized dataset is required, define and verify the sanitization process independently. Prefer generated business examples that preserve relevant shape without carrying real identities, credentials, or confidential documents.
Choose the isolation level deliberately. Separate databases provide a strong operational boundary but cost more to create. Separate schemas or tenant namespaces can work when credentials and queries enforce the boundary correctly. Test that a preview credential cannot access another preview or production, rather than relying on naming conventions alone.
Inspect what is built into the browser bundle
Next.js public environment variables are inlined during the build. Changing the runtime environment afterward does not replace values already embedded in client JavaScript. Build the preview with its intended public API origin and other public settings, or implement an explicit runtime configuration mechanism where promotion requires it.
Keep server-only credentials out of public variables and client components. A value being named like a secret does not protect it if the build exposes it. Inspect the generated bundle and network requests for accidental production endpoints as part of the preview smoke test.
Illustrative preview manifest fields:
preview_id: portal-pr-42
source_revision: immutable reviewed or proposed revision
public_origin: assigned preview URL
data_scope: synthetic tenant and isolated storage scope
provider_mode: sandbox or stub
expires_at: lifecycle deadline
cleanup_state: pending, active, or completed
The manifest should reference credentials rather than contain their values. Store it where the provisioning and cleanup components can access it under controlled permissions. A failed deployment must still leave enough inventory for cleanup to find partially created resources.
Route callbacks and jobs to the right environment
Configure authentication redirect URLs and provider webhook routes for the preview explicitly. Avoid a shared callback that guesses the environment from an untrusted request parameter. Verify the provider signature and resolve the destination through a trusted environment record or dedicated endpoint.
Background jobs need the same isolation. Include the preview scope in queue routing and business operation identity, and ensure workers use the preview's data credentials. A preview frontend backed by a production worker can cross the boundary even when its own database settings look correct.
Late callbacks are inevitable when environments are short-lived. After destruction, a callback should receive a deliberate response or enter a bounded quarantine path; it must not be reassigned to a new preview that reused the identifier. Retain a minimal tombstone or generation identifier when necessary to distinguish old and current environments.
Separate contribution trust from environment realism
A fork pull request may contain untrusted build scripts. Do not give it production credentials or a privileged deployment runner just to create a convenient preview. Use a restricted provisioning path, synthetic resources, and reviewed infrastructure definitions. Any approval to expose limited preview credentials should be explicit in the repository's trust model.
Use provider sandbox accounts or stubs for email, payment, and provisioning actions. A kill switch can add containment, but it should not be the only barrier preventing real effects. Verify that the preview's identity lacks production authority even if application code attempts an unexpected call.
Make cleanup independent of a successful close event
Delete resources when the preview closes, and run a separate expiry sweep for missed events and interrupted workflows. Cleanup should be repeat-safe and scoped by the manifest, never a broad name pattern that could match production. Remove credentials and callbacks as well as compute resources.
Test partial provisioning, repeated updates, late webhooks, and cleanup during an active job. The Next.js backend guide explains responsibility boundaries, and integration controls explains containment. SaaS implementation should make previews a reliable review tool rather than an accumulating collection of shared resources.