Guidemark React SDK

Guidemark is clarity infrastructure for React apps: a developer-first SDK for turning confusing product moments into guided clarity flows users can complete, developers can maintain, and answer engines can understand.

Published on npm as @guidemark/react.

This package exposes the high-level consumer API for guided clarity flows, including the GuidemarkFlow component, provider/hooks, signed runtime license tokens, and application-provided license validation. The published npm artifact is bundled without source maps. Public docs, examples, release notes, and issues live in the active source repository:

https://github.com/yaneyba/guidemark

This package is commercial software. See LICENSE.md in the published package or https://guidemark.dev/terms for the governing license terms.

Guidemark is the commercial product name, and @guidemark/react is the published package name.

Install

If you just purchased a license, start with the guided setup page:

https://guidemark.dev/start

Install the published package name from npm. For hosted Guidemark validation, install the explicit license client too:

pnpm add @guidemark/react @guidemark/license-client

If you publish the staged artifact under a different package name, install that name instead.

Quick Start

The fastest path to your first guided clarity flow is:

1. Install the package
2. Add your license key
3. Add one data-demo-id
4. Mount GuidemarkFlow
5. Confirm the first clarity step renders

Add the license key to your app environment:

VITE_PUBLIC_GUIDEMARK_LICENSE_KEY=gm_live_your_key_here

Security note: VITE_PUBLIC_GUIDEMARK_LICENSE_KEY is a site-bound public license key and is expected to be visible in browser bundles. Pair it with @guidemark/license-client or a custom license.validate callback so Guidemark can validate it against the licensed origins. Treat it like a publishable site identifier, not a private server secret. Never place API keys, admin tokens, Stripe secrets, webhook secrets, or other confidential credentials in VITE_* variables.

Add one stable anchor id to the confusing product moment you want to clarify:

<button data-demo-id="invite-user-button">Invite user</button>

Create a flow definition:

import type { GuidemarkFlowDefinition } from "@guidemark/react";

export const gettingStartedFlow: GuidemarkFlowDefinition = {
  id: "getting-started",
  version: 1,
  name: "Getting Started",
  steps: [
    {
      id: "welcome",
      title: "Welcome",
      body: "This flow clarifies the main workflow.",
      viewId: "dashboard",
      placement: "center",
    },
  ],
};

Mount GuidemarkFlow in your app:

import { GuidemarkFlow } from "@guidemark/react";
import { createHostedGuidemarkLicenseValidator } from "@guidemark/license-client";
import { gettingStartedFlow } from "./guidemark/getting-started-flow";

const validateGuidemarkLicense = createHostedGuidemarkLicenseValidator();

export function AppShell() {
  return (
    <GuidemarkFlow
      currentView="dashboard"
      navigateToView={viewId => {
        console.log("navigate", viewId);
      }}
      flow={gettingStartedFlow}
      autoStart
      license={{
        key: import.meta.env.VITE_PUBLIC_GUIDEMARK_LICENSE_KEY ?? "",
        mode: "block",
        validate: validateGuidemarkLicense,
      }}
      licenseProductName="Getting Started flow"
    >
      <App />
    </GuidemarkFlow>
  );
}

Success looks like this: the app loads, the public Guidemark license key validates for the current origin, and the first clarity step renders. If the key is missing, fake, or not valid for the origin, Guidemark blocks the wrapped experience. After that, customize the steps, anchors, analytics, and route navigation around the product moments where users need the most clarity.

Theme Integration

Guidemark follows the host app's theme by default. The overlay reads common real-color tokens such as --gm-surface-1, --gm-text-strong, --gm-text-body, --gm-accent, --color-popover, --color-popover-foreground, --color-primary, --color-secondary, and --color-border when they exist, so dark products should not get a forced white tour card.

For product-specific styling, define the Guidemark overlay variables in your app CSS:

:root {
  --guidemark-overlay-bg: hsl(var(--popover));
  --guidemark-overlay-fg: hsl(var(--popover-foreground));
  --guidemark-overlay-body: hsl(var(--muted-foreground));
  --guidemark-overlay-border: hsl(var(--border));
  --guidemark-overlay-primary-bg: hsl(var(--primary));
  --guidemark-overlay-primary-fg: hsl(var(--primary-foreground));
}

If no theme variables are present, the SDK falls back to a clean light default.

Licensing

Guidemark requires license configuration by default. The React SDK itself does not make automatic network requests; it accepts either a signed runtime license token that it can verify locally, or an explicit validator supplied by the host app.

If Guidemark issues you a signed runtime token, pass it with licenseToken:

<GuidemarkFlow
  currentView={currentView}
  navigateToView={navigateToView}
  flow={flow}
  licenseToken={import.meta.env.VITE_PUBLIC_GUIDEMARK_LICENSE_TOKEN ?? ""}
  licenseProductName="LoanFlow clarity flow"
  licenseHomeUrl="/"
/>

Runtime tokens are signed by Guidemark and checked locally against the SDK audience, expiration, origin, and host. A fake string or arbitrary public key does not pass.

For hosted runtime entitlement checks with a raw license key, add the explicit license client:

pnpm add @guidemark/license-client

Then pass its validator through the license prop. The validator receives the configured key plus Guidemark context and can return { valid: true } or an invalid result with a reason and message. When the validator returns an invalid result, block mode renders the default blocked-state UI and warn mode keeps the app visible with a local preview warning.

import { createHostedGuidemarkLicenseValidator } from "@guidemark/license-client";

const validateGuidemarkLicense = createHostedGuidemarkLicenseValidator();

<GuidemarkFlow
  currentView={currentView}
  navigateToView={navigateToView}
  flow={flow}
  license={{
    key: import.meta.env.VITE_PUBLIC_GUIDEMARK_LICENSE_KEY ?? "",
    mode: "block",
    validate: validateGuidemarkLicense,
  }}
/>;

Passing licenseKey without license.validate is intentionally rejected in 0.3.9 and later. Use licenseToken for local signed verification or license={{ key, validate }} for hosted validation.

For full docs and API reference, use https://guidemark.dev/docs.

For issues and runnable examples, use https://github.com/yaneyba/guidemark.