Coframe
Developer documentation
coframe.com (opens in a new tab) Open app (opens in a new tab)
DocumentationSDK Integrations

Next.js

Install the Coframe SDK in a Next.js app (App Router or Pages Router)

Guide~4 min read

Copy this guide and your current settings as a prompt for your AI agent.

Preview agent promptSee the guide, code and settings included when you copy.
Only this guide is included. Linked guides and videos are references.

This guide covers adding Coframe to a Next.js application. Because Next.js renders on the server before hydrating on the client, Coframe uses a waitForHydration flag so variant changes are applied only after React has fully mounted. Choose the section below that matches your router.

Watch: 65s — installing on the App Router and the Pages Router, and verifying in DevTools
On this page
  1. 01App Router
  2. 02Pages Router
  3. 03Verify it is working
  4. 04Optional configuration
Configure your installation

Set your project ID and options in the editor. Then follow the steps below using the updated code.

Installation editor

Configure once. Every code snippet in the guide updates with your settings.

Use your public project ID, or replace the placeholder before publishing.
App Router · Coframe.tsx

Use this in App Router · Coframe.tsx. Follow the placement instructions in this guide. Keep the hydration callback connected.

TSX · generated from your settings
"use client"
import { useEffect } from 'react'

export default function Coframe() {

    // Send page hydrated event
    useEffect(() => { 
      window.CFQ = window.CFQ || []; 
      window.CFQ.push({ pageHydrated: true })
    }, [])

    return (
        <>
            <script dangerouslySetInnerHTML={{
                __html: `
                (function () {
                  // Early exit for performance testing
                  if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');
                
                  // Coframe config
                  const config = {
                    projectId: 'YOUR_PROJECT_ID',
                    startTime: Date.now(),
                    timeoutMs: 1000,
                    currentUrl: window.location.href,
                    waitForHydration: true, // Wait for the framework readiness signal
                  };
                
                  // Prevent duplicate installation
                  const script_id = 'coframe-sdk-js';
                  if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');
                
                  // Coframe queue setup
                  (window.CFQ = window.CFQ || []).push({ config });
                
                  // Coframe antiflicker CSS
                  const style = document.createElement('style');
                  style.id = 'coframe-antiflicker';
                  style.textContent =
                    ':root { --cf-show: 0;}' +
                    'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
                  function hide() { document.head.appendChild(style); }
                  function show() {
                    document.documentElement.style.setProperty('--cf-show', '1');
                    style.parentNode && style.parentNode.removeChild(style);
                  }
                  hide(); setTimeout(show, config.timeoutMs);
                
                  // Coframe SDK JS
                  var edgeUrl = new URL('https://edge.cofra.me/cf.js');
                  edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
                
                  const script = document.createElement('script');
                  script.id = script_id;
                  script.async = true;
                  script.src = edgeUrl.toString();
                  script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
                  document.head.appendChild(script);
                })();
                `
            }} />
        </>
    )
}
5 scripts · 0 companions
Configuration2 on
Antiflicker mode

01App Router

Step 1 — Create the Coframe component

Create components/Coframe.tsx. This client component injects the Coframe installation script via dangerouslySetInnerHTML and fires a pageHydrated event after React mounts.

Replace YOUR_PROJECT_ID with the project ID from your Coframe dashboard.

TSX
"use client"
import { useEffect } from 'react'

export default function Coframe() {

    // Send page hydrated event
    useEffect(() => { 
      window.CFQ = window.CFQ || []; 
      window.CFQ.push({ pageHydrated: true })
    }, [])

    return (
        <>
            <script dangerouslySetInnerHTML={{
                __html: `
                (function () {
                  // Early exit for performance testing
                  if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');
                
                  // Coframe config
                  const config = {
                    projectId: 'YOUR_PROJECT_ID',
                    startTime: Date.now(),
                    timeoutMs: 1000,
                    currentUrl: window.location.href,
                    waitForHydration: true, // Wait for the framework readiness signal
                  };
                
                  // Prevent duplicate installation
                  const script_id = 'coframe-sdk-js';
                  if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');
                
                  // Coframe queue setup
                  (window.CFQ = window.CFQ || []).push({ config });
                
                  // Coframe antiflicker CSS
                  const style = document.createElement('style');
                  style.id = 'coframe-antiflicker';
                  style.textContent =
                    ':root { --cf-show: 0;}' +
                    'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
                  function hide() { document.head.appendChild(style); }
                  function show() {
                    document.documentElement.style.setProperty('--cf-show', '1');
                    style.parentNode && style.parentNode.removeChild(style);
                  }
                  hide(); setTimeout(show, config.timeoutMs);
                
                  // Coframe SDK JS
                  var edgeUrl = new URL('https://edge.cofra.me/cf.js');
                  edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
                
                  const script = document.createElement('script');
                  script.id = script_id;
                  script.async = true;
                  script.src = edgeUrl.toString();
                  script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
                  document.head.appendChild(script);
                })();
                `
            }} />
        </>
    )
}

Step 2 — Update your layout file

Import <Coframe /> in your root layout and render it inside <body> so it runs on every page.

TSX
import Coframe from './components/Coframe'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Coframe />
        {children}
      </body>
    </html>
  )
}

02Pages Router

Step 1 — Update _document.tsx

Add the Coframe installation script to your custom _document.tsx using next/script with strategy="beforeInteractive" so it runs before hydration.

Add the Script import and the <Script> block to your existing _document.tsx. The ... stands in for your existing document structure (the Html, Main, and NextScript parts).

TSX
import Script from 'next/script'
import { Head } from 'next/document'
...
<Head>
  <Script id='coframe-setup' strategy="beforeInteractive">
      {`
      (function () {
        // Early exit for performance testing
        if (/cf_disable/.test(location.search)) return console.warn('[Coframe] Disabled via URL parameter');
      
        // Coframe config
        const config = {
          projectId: 'YOUR_PROJECT_ID',
          startTime: Date.now(),
          timeoutMs: 1000,
          currentUrl: window.location.href,
          waitForHydration: true, // Wait for the framework readiness signal
        };
      
        // Prevent duplicate installation
        const script_id = 'coframe-sdk-js';
        if (document.getElementById(script_id)) return console.warn('[Coframe] SDK already installed');
      
        // Coframe queue setup
        (window.CFQ = window.CFQ || []).push({ config });
      
        // Coframe antiflicker CSS
        const style = document.createElement('style');
        style.id = 'coframe-antiflicker';
        style.textContent =
          ':root { --cf-show: 0;}' +
          'body { opacity: var(--cf-show) !important; transition: opacity 0.2s ease; }'
        function hide() { document.head.appendChild(style); }
        function show() {
          document.documentElement.style.setProperty('--cf-show', '1');
          style.parentNode && style.parentNode.removeChild(style);
        }
        hide(); setTimeout(show, config.timeoutMs);
      
        // Coframe SDK JS
        var edgeUrl = new URL('https://edge.cofra.me/cf.js');
        edgeUrl.searchParams.set('config', encodeURIComponent(JSON.stringify(config)));
      
        const script = document.createElement('script');
        script.id = script_id;
        script.async = true;
        script.src = edgeUrl.toString();
        script.onerror = () => { show(); console.error('[Coframe] SDK failed to load'); };
        document.head.appendChild(script);
      })();
      `}
  </Script>
</Head>

Step 2 — Create the Coframe component

Create components/Coframe.tsx. This component fires the pageHydrated event once React has mounted.

TSX
import React, { useEffect } from 'react';

function Coframe() {

    // Send page hydrated event
    useEffect(() => {
      window.CFQ = window.CFQ || [];
      window.CFQ.push({ pageHydrated: true })
    }, [])

  return null;
}

export default Coframe;

Step 3 — Add Coframe to _app.tsx

Import and render <Coframe /> in your custom _app.tsx so it appears on every page.

TSX
import Coframe from '../components/Coframe';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Coframe />
      <Component {...pageProps} />
    </>
  );
}

03Verify it is working

After running your app and loading a page in a browser:

  • Open the browser console and confirm there are no [Coframe] error messages.
  • In the Network tab, look for a request to edge.cofra.me/cf.js. A successful 200 response means the SDK loaded correctly.
  • Check that a coframe-sdk-js script element appears in the DOM (you can inspect the <head> in the Elements panel).

For a full walkthrough of how to validate the integration and confirm that Coframe is operating as expected, see Testing and Validation.

04Optional configuration

The default script is designed to work without additional configuration. Once the SDK is installed, you can tune behavior using the following guides:

  • SDK options — timeout, disable conditions, and other core settings
  • Identity settings — associate SDK activity with a known user identity
  • Tracking settings — control which events and page interactions Coframe records
  • Anti-flicker — understand how the anti-flicker mechanism works and how to adjust it for your performance requirements

Related reading

Testing and ValidationVerify the Coframe SDK is installed and measure its impactSDK OptionsThe complete Coframe configuration reference — antiflicker, analytics callback, feature flag control, cookie consent, cookieless, conversion events, tracking-only mode, and CSP nonceIdentity SettingsCookieless mode — provide your own visitor identity with setUserToken

Content and video lessons from Coframe documentation. Code examples are not executed on this page.

BACK TOSDK Integrations

Documentation

Open Coframe App

Search documentation

Search all guides and references↑ ↓ Navigate · Esc Close