Skip to Content
WidgetInstallation

Installation

Two ways to add the Unchurn widget to your app: a CDN script tag for no-build setups, and an npm package for full framework integration.

CDN

The CDN path requires no build step and no Node.js server.

Add the script tag

<script src="https://cdn.unchurn.dev/widget.js" async></script>

Place this in <head> or just before </body> on any page that hosts a cancel button.

What gets exposed

Once the script loads, window.unchurn is available globally:

window.unchurn.showCancelFlow({
  merchantId: 'mch_YOUR_MERCHANT_ID',
  subscriptionId: 'sub_STRIPE_SUB_ID',
})

All widget features — outcomes, callbacks, auth tokens — work identically over CDN. The only thing the CDN path cannot do is mint server-signed tokens, because there is no server component.

When to use CDN

  • Proof of concept or staging environments
  • Plain HTML / non-Node.js stacks
  • Any setup where you want to skip a build step

For production you should use the npm package with server-signed auth tokens (see Auth Tokens).

npm

npm install @unchurn.dev/widget

The package exposes three entry points. Import only what your environment supports.

Entry points

Import pathWhat it containsRuns in
@unchurn.dev/widgetCore embed API (showCancelFlow, types)Browser / any framework
@unchurn.dev/widget/reactuseUnchurn hookBrowser (React 18+)
@unchurn.dev/widget/nextjscreateUnchurnHandler server helperNode.js only

@unchurn.dev/widget is the base. Use it in any framework — Vue, Svelte, vanilla JS bundled with Webpack or Vite — wherever you need to call showCancelFlow directly.

@unchurn.dev/widget/react wraps the core embed API in a React hook that manages token fetching, caching, and deduplication. Import this in client components alongside the base package.

@unchurn.dev/widget/nextjs is a Node.js-only server helper that creates a Next.js Route Handler for minting signed auth tokens. Never import this in browser code.

Peer dependencies

The React path requires React and React DOM 18 or later as peer dependencies. Install them if your project does not already have them:

npm install react@^18 react-dom@^18

The core and Next.js paths have no peer dependencies.

Environment variables

Add these to your .env.local (or your hosting provider’s environment config):

# Required for server-signed tokens
UNCHURN_SECRET=your_32_char_hex_secret_from_dashboard
UNCHURN_MERCHANT_ID=mch_YOUR_MERCHANT_ID

UNCHURN_SECRET is a 32+ character hex string. Retrieve it from your Unchurn dashboard under Settings > Signing secret. Treat it as a password — never expose it to the browser.

UNCHURN_MERCHANT_ID is safe to include in client-side code and is also passed to showCancelFlow from the browser.

Next steps

Last updated on
Auth integrationsAuth Tokens