Next.js: Glopzi Docs

The two-tag pattern

For Next.js (and every other streaming-SSR framework), Glopzi needs two tags: a CSS link and a script.

HTML

<link
  rel="stylesheet"
  href="https://cdn.glopzi.com/YOUR_API_KEY.css"
/>
<script
  src="https://cdn.glopzi.com/modules/glopzi.js"
  data-glopzi-key="YOUR_API_KEY"
  async
></script>

The link tag applies before first paint and prevents flicker on initial load. The script loads the runtime and runs your animations. Both reference the same API key.

App Router

In app/layout.tsx, render both tags inside <head>:

TSXapp/layout.tsx

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link
          rel="stylesheet"
          href="https://cdn.glopzi.com/YOUR_API_KEY.css"
        />
      </head>
      <body>
        {children}
        <script
          src="https://cdn.glopzi.com/modules/glopzi.js"
          data-glopzi-key="YOUR_API_KEY"
          async
        />
      </body>
    </html>
  );
}

Next.js renders raw <link> tags inside <head> without preprocessing, so this just works.

Pages Router

In pages/_document.tsx, use Next’s Head component for the link and a regular script tag in body:

TSXpages/_document.tsx

import { Html, Head, Main, NextScript } from "next/document";

export default function Document() {
  return (
    <Html lang="en">
      <Head>
        <link
          rel="stylesheet"
          href="https://cdn.glopzi.com/YOUR_API_KEY.css"
        />
      </Head>
      <body>
        <Main />
        <NextScript />
        <script
          src="https://cdn.glopzi.com/modules/glopzi.js"
          data-glopzi-key="YOUR_API_KEY"
          async
        />
      </body>
    </Html>
  );
}

Why the link tag

Next.js streams HTML to the browser as it renders. The browser starts painting before the closing </html>arrives. If Glopzi’s anti-FOUC stylesheet only existed inside the JavaScript bundle, the bundle would arrive after first paint and you’d see elements at their natural state for a moment, then jump into their animation start positions.

The separate link tag arrives during head parsing, before first paint. The styles apply preemptively, so first paint already shows elements in their pre-animation state. No flicker.

Note

For deeper background, see Anti-FOUC stylesheet in the Performance article.

Common pitfalls

Animations target elements that get hydrated. Glopzi waits for window.loadbefore initializing, which gives Next.js time to hydrate. If you still see selectors fail to match, the target element may not exist on the server-rendered HTML; check that it’s not inside a client-only component that mounts after load.
Strict CSP headers. If your Next.js config sets a Content Security Policy, addhttps://cdn.glopzi.com toscript-src and style-src. Otherwise the browser blocks our resources.
Using next/script instead of plain script. Both work. The plain script tag is simpler and doesn’t require importing anything; we recommend it.
Editor opens but the page is blank. Verify the page renders normally outside the editor first. If your page requires login or specific cookies, the editor frame won’t see them.

Next steps

Quickstart: any website: the generic walkthrough.
Astro, Remix, SvelteKit: same pattern, framework-specific syntax.
Performance and Core Web Vitals: the FOUC mechanic explained.