knock-in-app-ui

name	knock-in-app-ui
description	Guidance for implementing Knock in-app UI in a web app, with a focus on setting up, rendering, and debugging Knock guides in React.

Knock in-app UI skill

This skill helps you build in-app UI with Knock. It covers the two in-app products — feeds and guides — at a high level, then goes deep on guides: provider setup, rendering with hooks, and debugging.

Reference: https://docs.knock.app/in-app-ui/overview

Overview

The skill is organized into four focused rule files. Client-framework guidance is scoped per framework via a -<framework> suffix (currently only React). Cross-framework concepts live in unsuffixed files.

1. Feeds vs. guides (framework-agnostic) — which product to pick for a given surface and why
2. Setting up the guide providers in React — KnockProvider and KnockGuideProvider props, where each value comes from, and how to sequence them
3. Rendering guides in React — building a guide component with useGuide / useGuides, typed content, and engagement tracking
4. Debugging guides (framework-agnostic) — the guides toolbar, the triage checklist, and testing workflow

Framework scope: right now this skill only covers React (@knocklabs/react). If the user is building with Vue, Svelte, plain JS, React Native, iOS, or Android, stop and ask how they'd like to proceed — do not adapt the React rules to another client SDK on your own.

How to use this skill

When deciding what to build

Start with rules/feeds-vs-guides.md:

• Confirm the surface you're building is actually a guide, not a feed
• Check the decision table before picking a direction
• If the answer is "both," wrap the app in KnockProvider once and render each product's provider where it's needed

When adding guides to a React app for the first time

1. Read rules/setup-guide-providers-react.md
2. Before running any CLI commands, confirm the CLI is authenticated and which Knock environment this setup is for. First run knock whoami — if it errors with something like "not authenticated" or "no user session," run knock login and ask the user to complete the browser flow before continuing (the CLI persists the session so this is a one-time step per machine). Only after knock whoami succeeds, run knock environment list and ask the user to pick (the CLI defaults to development, but most real integrations target production). Remember that slug as <env-slug> and pass --environment <env-slug> on every subsequent environment-scoped knock command.
3. Before asking the user anything about the channel, discover channelId via the Knock CLI: run knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'. Channels are account-scoped, so this command does not take --environment. If it prints a UUID, use it — do not ask the user to confirm or re-paste. Only ask the user if the CLI returns nothing or errors. See the rule file's "Where to get channelId" procedure for the full fallback order.
4. Ask the user only for values that can't be auto-discovered — primarily the public apiKey for the chosen environment (and confirm user.id is coming from the app's auth context). Do not bundle the apiKey ask with channelId.
5. Wire KnockProvider + KnockGuideProvider at the top of the tree.
6. Gate readyToTarget on any async data your targeting depends on.
7. Get a real guide rendering before stopping. Run knock guide list --environment <env-slug> --json, show the user the options (key, name, each step's schema_key), and build the first component against a real guide's actual values. Do not scaffold with placeholder strings like "changelog-card". Fetch the message type schema with knock message-type get <schema_key> --environment <env-slug> --json so the content is typed. If the environment has no guides, offer to scaffold a test one via the Knock CLI (knock guide new → edit the JSON → knock guide push --environment <env-slug>) using a built-in message type (card, banner, or modal) with obvious-placeholder content — don't stall waiting for manual dashboard setup. See rules/rendering-guides-react.md → "First guide: discover real guides via CLI before writing code" for the full procedure including the empty-environment branch.
8. Flag anything that still needs the user (paste pk_ key, flip the guide to active in the dashboard, restart dev server) explicitly — don't leave them to discover it by absence.

When building a new guide component in React

1. Follow the workflow in rules/rendering-guides-react.md
2. Discover the target guide (or message type) via the Knock CLI before picking values. knock guide list --environment <env-slug> --json for the guide's key / step schema_key; knock message-type get <schema_key> --environment <env-slug> --json for the content schema. Avoid placeholder strings.
3. Pick useGuide for single-guide surfaces, useGuides for lists
4. Define a TypeScript type that mirrors the message type schema you just pulled
5. Wire markAsSeen, markAsInteracted, and markAsArchived — custom components must do this themselves

When a guide isn't rendering

1. Open rules/debugging-guides.md and work the triage checklist top to bottom
2. Turn on the guides toolbar (?knock_guide_toolbar=true) first — it answers most questions in seconds
3. Distinguish server-side (targeting/eligibility) from client-side (provider/component) failures before digging deeper

Rule files reference

• rules/feeds-vs-guides.md — product selection between feeds and guides (framework-agnostic)
• rules/setup-guide-providers-react.md — configuring KnockProvider and KnockGuideProvider for guides (React)
• rules/rendering-guides-react.md — useGuide, useGuides, typed content, engagement tracking (React)
• rules/debugging-guides.md — toolbar, triage checklist, testing workflow (framework-agnostic)

Quick reference

The examples below are React. For any other client SDK, see the note at the top of Overview before proceeding.

Providers (minimum viable setup — React)

<KnockProvider
  apiKey={process.env.NEXT_PUBLIC_KNOCK_API_KEY}
  user={{ id: currentUser.id }}
>
  <KnockGuideProvider
    channelId={process.env.NEXT_PUBLIC_KNOCK_GUIDE_CHANNEL_ID}
    readyToTarget
    listenForUpdates
  >
    {children}
  </KnockGuideProvider>
</KnockProvider>

Where to source each value

• Auth first, then environment — Knock is environment-scoped. Before any CLI command, verify the CLI is authenticated with knock whoami; if it errors, run knock login and wait for the user to complete the browser flow. Then run knock environment list and confirm the target slug (production, development, …) with the user. Pass --environment <env-slug> on every subsequent environment-scoped knock command. Don't rely on the CLI's development default.

• apiKey — Knock dashboard → Platform → API keys → public pk_... key from the tab for the chosen environment (switch envs via the dashboard's environment selector first; remind the user to copy the key for the right env)

• user.id — your auth context; must match the id used when identifying the user from your backend

• channelId — the UUID of the guide channel, not its key. Channels are account-scoped, so knock channel list does not take --environment. Always attempt CLI discovery before asking the user:

  knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
  

  If this prints a UUID, use it directly — don't prompt for confirmation. The default guide channel key is knock-guide (type in_app_guide). Fall back to the dashboard (Settings → Integrations → Channels) only if the CLI returns nothing or errors. See rules/setup-guide-providers-react.md for the full procedure.

Hooks at a glance

• useGuide({ type }) — one guide by message type
• useGuide({ key }) — one specific guide by key
• useGuides({ type }) — array of guides by message type
• useGuideContext() — low-level client access

Engagement methods

• step.markAsSeen() — impression (call from useEffect keyed on step)
• step.markAsInteracted() — primary action
• step.markAsArchived() — dismissal; removes the guide for this user going forward

First stop when something's wrong

Append ?knock_guide_toolbar=true to any URL. The toolbar shows all guides, which are active, which this user is eligible for, and why the rest were filtered out.

Best practices summary

1. Pick the right product. Feeds for chronological lists, guides for targeted UI.
2. Mount providers once, high in the tree. Inside your auth boundary, above any route that renders guides.
3. Never pass a placeholder user. Wait for auth to resolve before mounting KnockProvider.
4. Gate readyToTarget on async data your targeting rules depend on.
5. Type your content. useGuide<T> should mirror the Knock message type schema.
6. Always handle engagement. Custom components must call markAsSeen, markAsInteracted, and markAsArchived themselves.
7. Use the toolbar first. Most "the guide isn't showing" questions are answered in seconds.