Next.js boilerplate with Crisp

What a chat context actually is

Everything pushed with session:data, session:segments or user:* is stored by Crisp, shown to every operator in the workspace, retained with the conversation, and forwarded to whatever integrations that workspace has enabled: Slack, email, a CRM, an automation. Treat it as a third-party log with a friendly UI.

Never push a credential

• No session tokens, JWTs, API keys, signed URLs, password reset links, one-time codes, card numbers or cookie values. Not "temporarily", not "for debugging", not in a segment name.
• Always go through setSessionData() from @/lib/support/crisp. It strips keys matching token|secret|password|authorization|cookie|api_key|session|jwt|card|cvv and values shaped like credentials, and warns in development. Never call window.$crisp.push(["set", "session:data", ...]) directly to get around it.
• Do not spread an object in: setSessionData({ ...user }) ships every field the type gains later, including the ones added after this line was written. Name the three or four keys an operator actually needs.
• If an operator needs to see something sensitive to help, they look it up in your admin panel behind their own login. That is what the admin panel is for, and it leaves an audit trail Crisp cannot.

Identify only from the server

• An email set from the browser is a claim. Pass an identity resolved on the server by currentSupportIdentity(), with the HMAC signature from signIdentity(), so Crisp marks the conversation verified.
• That helper reads the session through @/lib/auth/session and nothing else. Never import an auth SDK from src/lib/support/**: the support layer works with whichever auth battery is installed precisely because it does not know which one that is.
• SessionUser.email and .name are both nullable. Push each only when it is there: an account with no address gets an anonymous conversation, never one labelled with a placeholder.
• Never read an email out of a form field, a query parameter or localStorage and push it as the user's identity. That is how a support team ends up acting on an impersonated address.
• Without CRISP_IDENTITY_SECRET set, every address in the inbox is unverified. Say so in your support runbook and never action an account change on the strength of an unverified label.
• Call resetSession() on sign-out, before the redirect. Otherwise the next person on that browser opens the previous user's conversation history.

Minimal by default

• Useful context is small and stable: plan, account id, app version, the page the chat was opened from, the feature area. That removes the first three questions of a support conversation and nothing more.
• No free text a user typed: a search query or a note can contain anything, including a third party's personal data.
• No internal identifiers that mean nothing to an operator. If nobody in support can act on a field, it is noise that will still be there in a year.

Segments are routing, not data

• Segments drive who picks a conversation up and which automations fire. Keep them few, lowercase and stable: billing, onboarding, enterprise.
• Never encode a value in a segment: plan_pro is a segment, user_1a2b3c is a leak dressed as routing.

One loader, and it is <CrispWidget />

• Crisp is loaded in exactly one place: src/lib/support/crisp-widget.tsx, through next/script with strategy="lazyOnload". Never paste Crisp's own snippet into a layout, a <head>, an inline <script> or dangerouslySetInnerHTML.

• lazyOnload is the strategy, deliberately. It downloads during browser idle time, after hydration.

  • beforeInteractive puts a third-party script ahead of your own application code. Indefensible for a chat bubble.
  • afterInteractive still competes with your JavaScript for the main thread during the most sensitive part of the load.
  • A bare <script src> in a layout blocks parsing and lands directly in LCP.

• Nothing else may block on Crisp. No await, no spinner waiting for it, no component that renders null until crispLoaded() is true. If the script never arrives (an extension blocked it, the CDN is down) the product must be entirely unaffected.

Consent gates the render, not the visibility

• Crisp writes cookies and a session identifier the moment l.js executes. Hiding the launcher afterwards does not undo that.
• Therefore: when consent is required and not granted, the <Script> element is not rendered at all. hasSupportConsent() from src/lib/support/consent.ts is the only source of that decision, and CONSENT_MODE is the only place the policy is set.
• Never load the widget "just for signed-in users" as a consent workaround. Being signed in is not consent to third-party tracking cookies.
• Consent must be as easy to withdraw as to give. revokeSupportConsent() reloads the page, because Crisp has no teardown API once it is running.

Route rules

• HIDDEN_ROUTES in crisp-widget.tsx lists the pages where the launcher must not appear: the marketing home page, sign-in, sign-up, pricing. A floating bubble competes with the one action those pages exist for.
• Navigating onto a hidden route calls hideLauncher(); navigating off calls showLauncher(). Neither unloads the script, because nothing can.
• On pages where support belongs but the bubble does not, use <SupportButton /> and keep the launcher hidden.

Hydration

• crisp-widget.tsx and every component that reads consent are client components. Consent lives in localStorage, which does not exist on the server, so it is read in an effect after mount, never during render, which would make the server and client markup disagree.
• Never render different markup on the server and client based on typeof window. That is a hydration error, and in production React silently keeps the server output, so the bug only appears for real users.
• Nothing in src/lib/support/** may be imported by a Server Component except identity.ts, which is server-only by design and reads CRISP_IDENTITY_SECRET.