stepskit

The official npm package for StepsKit — product tours, tooltips, surveys and announcements for your web app.

This is a typed loader (~1 KB), not the whole runtime. It installs a pre-load call queue, injects the evergreen StepsKit runtime from cdn.stepskit.com, and gives you a fully typed API. The npm version versions the loader — the tour engine itself streams from the CDN and is always current, so you never need to bump this package to pick up engine fixes.

Quickstart

npm install stepskit

import stepskit from "stepskit";

stepskit.init("YOUR_API_KEY");

Call init() once at your app's entry point. It is SSR-safe (a no-op on the server) and idempotent (calling it twice injects nothing).

Migrating from the <script> snippet? Remove the snippet when you add the package — the snippet injects unconditionally, and two loaders mean two embed instances.

React / Next.js

import { StepsKit } from "stepskit/react";

// Next.js App Router: app/layout.tsx (it's already a client-safe component)
// Vite/CRA: your top-level <App />
<StepsKit
  apiKey="YOUR_API_KEY"
  user={{ id: user.id, email: user.email, plan: user.plan }}
/>;

The component renders nothing, loads StepsKit once (StrictMode-safe), and identifies the user when the user prop appears or its values change — passing a new object with the same values does not re-identify.

Identify your users

stepskit.identify({ id: "user_123", email: "[email protected]", plan: "pro" });

Without an id, show-once frequency capping and audience targeting silently do nothing — every visitor is anonymous. Call identify once, when your auth state resolves. Calls made before the runtime finishes loading (or even before init()) are queued and replayed in order, so identity is always set before the first tours fetch.

API

The full API is documented at stepskit.com/docs/api. Everything on window.stepskit is on the stepskit import, fully typed:

| Method | Pre-load behavior | | --- | --- | | identify(user) | queued | | setUserAttributes(attrs, opts?) | queued | | playTour(id) / stopTour() / refresh() | queued | | on(event, fn) / off(event, fn) | queued | | dismissAnnouncement(id) / destroy() / track() | queued | | isPlaying() | false | | getTours() | [] | | getUserAttributes() | undefined | | validateEnvironment() | undefined |

Options

stepskit.init("YOUR_API_KEY", {
  apiUrl: "https://stepskit.your-domain.com", // self-hosted / local API origin
  debug: true, // [StepsKit] info logs
  user: { id: "user_123" }, // identify as part of init
  nonce: cspNonce, // CSP nonce for the injected <script>
});

If your Content-Security-Policy restricts script-src, allow https://cdn.stepskit.com (and https://stepskit.com for connect-src).

Plain HTML / CMS / GTM

No build step? Use the copy-paste <script> snippet from your StepsKit dashboard instead — see stepskit.com/docs/install/js.

CommonJS

The package ships both ESM and CJS. In CommonJS, use the named export:

const { stepskit } = require("stepskit");