Developer docs

npm package

@deployseal/react installs the DeploySeal widget from a React app: Next.js, Vite, Create React App, or a headless storefront whose layout lives in code. One component in the root layout adds the same widget tag the snippet would, once, with the build marker from your CI and data-ds-installer so the site page knows where the widget came from. It has no runtime dependencies; the widget itself still loads from our CDN.

<script
  src="https://cdn.deployseal.com/ds-widget.js"
  data-ds-site-key="ls_••••••••••••••••••••••••••••••••••••"
  data-ds-environment="staging"
  data-ds-build="a1b2c3d4e5f6"
  data-ds-installer="npm-react/1.0.1"
  async
></script>

Install

npm install @deployseal/react

You need an environment's public key. In DeploySeal open Sites → your site and expand the environment under Environments. Each environment has its own key, so staging and a preview environment each get theirs. React 18 or later.

Next.js (App Router)

Place the component once, in the root layout. It renders nothing, and the package is a client component, so a server layout can render it directly. Where the key is not set, for example in production if you only test on staging, it is not rendered at all.

// app/layout.tsx
import { DeploySeal } from '@deployseal/react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {process.env.NEXT_PUBLIC_DEPLOYSEAL_SITE_KEY && (
          <DeploySeal
            siteKey={process.env.NEXT_PUBLIC_DEPLOYSEAL_SITE_KEY}
            environment={process.env.NEXT_PUBLIC_DEPLOYSEAL_ENVIRONMENT}
            build={process.env.NEXT_PUBLIC_DEPLOYSEAL_BUILD}
          />
        )}
      </body>
    </html>
  )
}

// next.config.js — the commit SHA from your CI becomes the build marker
module.exports = {
  env: {
    NEXT_PUBLIC_DEPLOYSEAL_BUILD: process.env.VERCEL_GIT_COMMIT_SHA ?? process.env.GITHUB_SHA,
  },
}

Set NEXT_PUBLIC_DEPLOYSEAL_SITE_KEY and NEXT_PUBLIC_DEPLOYSEAL_ENVIRONMENT per environment in your host's settings. Next.js inlines public variables when it builds, so rebuild after changing them.

Without the package: next/script with the data attributes renders the same tag. The package adds what that leaves to you: the environment label in the form DeploySeal compares, no placeholder or empty build marker, the installer stamp, and no second tag when one is already on the page.

import Script from 'next/script'

<Script
  src="https://cdn.deployseal.com/ds-widget.js"
  data-ds-site-key={process.env.NEXT_PUBLIC_DEPLOYSEAL_SITE_KEY}
  data-ds-environment="staging"
  data-ds-build={process.env.NEXT_PUBLIC_DEPLOYSEAL_BUILD}
  strategy="afterInteractive"
/>

Vite, Create React App and plain JavaScript

// main.tsx
import { DeploySeal } from '@deployseal/react'

createRoot(document.getElementById('root')!).render(
  <>
    <App />
    <DeploySeal
      siteKey={import.meta.env.VITE_DEPLOYSEAL_SITE_KEY}
      environment={import.meta.env.VITE_DEPLOYSEAL_ENVIRONMENT}
      build={import.meta.env.VITE_DEPLOYSEAL_BUILD}
    />
  </>,
)

Create React App reads process.env.REACT_APP_DEPLOYSEAL_… instead. Without React, call the function the component uses; it returns a function that removes the tag.

import { installDeploySeal } from '@deployseal/react'

const uninstall = installDeploySeal({ siteKey: 'ls_…', environment: 'staging', build: 'a1b2c3d' })

Props

Build marker

Send the commit SHA from your CI: at least seven characters, one token, no spaces, changing on every deployment. The readiness report compares it with the release the campaign declares, so the people signing off can see that the tested build is the one being released; a short and a full SHA confirm each other. Vercel exposes VERCEL_GIT_COMMIT_SHA, Netlify COMMIT_REF, GitHub Actions GITHUB_SHA, GitLab CI_COMMIT_SHA. The build marker rules cover versions and version-plus-SHA markers.

Origins

The widget answers only on the environment's allowed origins, matched exactly: scheme, host and port, no wildcards, no subdomains. https://staging.example.com and http://staging.example.com are different origins, and so is every preview URL. Register each origin testers will use on the environment before inviting them.

What it sends

• No recording until an invited tester is on a registered origin. For every other visitor the widget stays hidden.
• One heartbeat per page load: the page URL without its hash and sensitive query keys, the page title, the environment label, the build marker, the widget version and the installer. It is what shows the install as Live on the site page. On an origin the environment does not list, the API refuses it and nothing is recorded.
• Sessions, screenshots and issues only for a tester with an active invitation, honouring data-ds-mask and .ds-mask as described in the widget reference.

One tag per page

If the page already carries a DeploySeal tag, from a pasted snippet or a plugin, or the widget's loader has already run, the package adds nothing and says so in the console. Remove the pasted snippet when you switch to the package: while both are live the environment card shows an amber warning that two install paths are live, and the evidence would have two sources.

Troubleshooting