Integration guide

Asklify + Next.js

Use next/script with the lazyOnload strategy so the widget never competes with your page's critical resources. Works with both the App Router and the Pages Router.

Prerequisite: an Asklify project with some knowledge added — the quickstart covers that in a couple of minutes. You'll need your public project ID (pub_...) from Widget → Install.

Add the script to your root layout

App Router: drop the component below into app/layout.tsx. The widget loads after the page becomes interactive.

Pages Router variant

pages/_app.tsx

import Script from "next/script";
import type { AppProps } from "next/app";

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://api.asklify.in/widget.js"
        data-project-id={process.env.NEXT_PUBLIC_ASKLIFY_PROJECT_ID}
        strategy="lazyOnload"
      />
    </>
  );
}

Set the env var

.env.local

NEXT_PUBLIC_ASKLIFY_PROJECT_ID=pub_YOUR_PROJECT_ID

Ready-to-use template

Copy, paste, replace the project ID — that's the whole integration:

app/layout.tsx

import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://api.asklify.in/widget.js"
          data-project-id={process.env.NEXT_PUBLIC_ASKLIFY_PROJECT_ID}
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

The public project ID is safe in NEXT_PUBLIC_ env vars — it's not a secret.

All appearance and behavior — name, greeting, colors, theme, position, suggested questions — is configured in your dashboard under Widget settings and applies instantly without redeploying. See the widget configuration reference.

Event handling

To react to what happens in conversations — a chat starting, a customer requesting a human, feedback submitted — subscribe to webhooks. For fully custom experiences, the REST API exposes chat with streaming, knowledge search, and conversation transcripts.

Best practices

strategy="lazyOnload" keeps the widget entirely off your Core Web Vitals.
For localized sites, the same project works across locales — the assistant answers in the user's language.
Server-side API calls (e.g. ingesting docs in a route handler) should use an sk_ key stored in a server-only env var.

Troubleshooting

Widget not loading — confirm the env var is prefixed NEXT_PUBLIC_ and you restarted next dev after adding it.
Hydration warnings — the widget injects DOM outside React's tree, so it never causes hydration mismatches; warnings come from elsewhere.

Still stuck? Check the error reference or email hello@asklify.in.