Skip to main content

Ask AI assistant widget for Next.js

Add an AI assistant or AI search widget to your Next.js site. You can also connect AI agents through MCP, with or without installing the widget.

Prerequisites​

Add the assistant widget​

Assistant widget for docs

  1. Install the Biel.ai package:

    npm install biel-react biel-search
    Info

    For Yarn, use yarn add biel-react biel-search.

  2. Create a wrapper for the assistant by creating a file at components/biel-search.tsx:

    'use client';

    import { useEffect, type ComponentProps } from 'react';
    import { BielButton } from 'biel-react';
    import bielPackage from 'biel-search/package.json';
    import 'biel-search/dist/biel-search/biel-search.css';

    const DynamicBielButtonComponent = (props: ComponentProps<typeof BielButton>) => {
    useEffect(() => {
        if (!document.querySelector('script[data-biel]')) {
          const script = document.createElement('script');
          script.type = 'module';
          script.src = `https://cdn.jsdelivr.net/npm/biel-search@${bielPackage.version}/dist/biel-search/biel-search.esm.js`;
          script.dataset.biel = '';
          document.head.appendChild(script);
        }
    }, []);

    return <BielButton {...props} />;
    };

    export default DynamicBielButtonComponent;

  3. Create components/DocumentationChat.tsx for the browser-only widget entry point:

    'use client'
    import dynamic from 'next/dynamic';

    const DynamicBielButton = dynamic(() => import('@/components/biel-search'), {
        ssr: false,
    });

    export default function DocumentationChat() {
    return (
    <div className="App">
    {/* Other components and content */}
        <DynamicBielButton
            project="<YOUR_PROJECT_ID>"
            header-title="Biel.ai assistant"
            button-position="bottom-right"
            modal-position="bottom-right"
            button-style="dark">
            Ask AI
        </DynamicBielButton>
    </div>
    );
    }

    Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

  4. Import DocumentationChat in your existing app/layout.tsx or pages/_app.tsx and render <DocumentationChat /> alongside the existing page content. Keep your root layout's <html>, <body>, and metadata. The client boundary belongs in DocumentationChat, not the root layout.

  5. Run npm run dev and verify that the assistant appears and works on your site.

Add the search widget​

  1. Install the React package:

    npm install biel-react biel-search

  2. Create components/BielSearch.tsx:

    'use client';

    import { useEffect } from 'react';
    import { BielSearchButton } from 'biel-react';
    import bielPackage from 'biel-search/package.json';

    export default function BielSearch() {
      useEffect(() => {
        if (!document.querySelector('script[data-biel]')) {
          const script = document.createElement('script');
          script.type = 'module';
          script.src = `https://cdn.jsdelivr.net/npm/biel-search@${bielPackage.version}/dist/biel-search/biel-search.esm.js`;
          script.dataset.biel = '';
          document.head.appendChild(script);
        }
      }, []);

      return (
        <BielSearchButton project="<YOUR_PROJECT_ID>" button-style="rounded">
          Search
        </BielSearchButton>
      );
    }

    Replace <YOUR_PROJECT_ID> with your project ID.

  3. Import the widget stylesheet in app/layout.tsx, or in pages/_app.tsx for the Pages Router:

    import 'biel-search/dist/biel-search/biel-search.css';

  4. Import and render <BielSearch /> in your header or navigation component:

    import BielSearch from '@/components/BielSearch';

    // Inside your existing header:
    <BielSearch />

  5. Run npm run dev. Open Search, enter a documentation term, and open a result. Keep your root layout’s existing HTML, metadata, and providers.

Connect AI agents with MCP​

Let AI tools search and read your indexed documentation. MCP is available on every plan and during your trial.

  1. In the Biel.ai dashboard, open your project’s Settings > MCP.
  2. Select Enable MCP server and click Save.
  3. In the widget, open Connect via MCP using the <> button. Select your AI client or choose MCP URL to copy the endpoint into its settings.

Without the widget: after enabling MCP, copy MCP endpoint from Settings > MCP and add it to your AI client. No widget installation or website changes are required.

The widget also exposes WebMCP tools to compatible browser agents visiting your site. Use the latest widget release and keep Enable WebMCP selected in Settings > MCP.

Next steps​