Seatext library

How to Install SeaText on a Headless Website

Install SeaText on a headless website by adding the SeaText JavaScript snippet to your HTML template or layout file, typically in the <head> or before the closing </body> tag. Use the "General / Custom"...

Quick Answer: Add the Snippet to Your HTML Template

For a headless website — whether it's a static site generator (Next.js, Astro, Gatsby), a single-page application (React, Vue, Svelte), or a custom server-rendered frontend — the installation is the same: paste the SeaText snippet into the shared layout or base template that wraps every page. The snippet loads the SeaText engine, which then rewrites text, translates content, or runs personalization agents on the client side.

This approach works because SeaText runs entirely in the browser. It does not require server-side code, database changes, or a CMS plugin. The snippet is a small JavaScript tag that loads from SeaText's CDN and executes on every page view. Once installed, you can activate agents from the SeaText dashboard without touching your code again.

Why Headless Sites Need a Client-Side Snippet

Headless architectures separate the content backend from the presentation layer. The frontend fetches data via APIs and renders it in the browser. This means there is no single server-side template where you can inject code that runs before the page is served. The only universal injection point is the HTML shell that wraps your application.

SeaText's client-side approach fits this model perfectly. It observes the DOM after the page loads, then applies transformations based on the visitor's intent, language, or referral source. Because it runs in the browser, it works with any framework that outputs HTML — from React to plain static files.

This also means you can test SeaText locally without a production deployment. Run your dev server, open the page, and the snippet will execute exactly as it would in production. The dashboard will show the installation as active once the first request hits the CDN.

Prerequisites Before You Start

  • A SeaText account (free pilot or paid plan).
  • Access to your project's base HTML template or layout component.
  • Ability to deploy a new build to your hosting (Vercel, Netlify, Cloudflare Pages, AWS Amplify, custom CI/CD, etc.).
  • No server-side SeaText logic is required; the snippet runs entirely in the browser.
  • Basic familiarity with your frontend's build and deployment process.

You do not need to modify your content API, database, or serverless functions. The snippet is self-contained and does not interfere with your existing JavaScript. It loads asynchronously, so it will not block rendering or cause layout shifts.

Step-by-Step Installation

  1. Log in to SeaText and open the dashboard.
  2. Choose "General / Custom" from the platform list (this is the option for any site not covered by a dedicated plugin).
  3. Copy the provided JavaScript snippet. It looks like a small <script> tag with your project ID.
  4. Paste the snippet into your base layout.
    • Next.js (App Router): app/layout.tsx inside <head> or at the top of <body>.
    • Astro: src/layouts/BaseLayout.astro in the <head>.
    • Gatsby: src/components/layout.js or use gatsby-ssr.js with onRenderBody.
    • Remix: app/root.tsx in the <head> export.
    • Plain HTML / static site: every .html file or your templating engine's master layout.
    • Vue/Nuxt: nuxt.config.ts via the head.script option, or in app.vue.
    • SvelteKit: src/app.html in the <head>.
    • Hugo/11ty: in your base template's <head>.
  5. Commit and deploy. The next build will include SeaText on every page.

If you use a monorepo or a component library, place the snippet in the root layout that wraps all routes. This ensures every page, including error pages and redirects, gets the snippet. For static sites, you can use a partial or include file to avoid duplicating the code.

Verification: Confirm It's Working

After deployment, open any page in a browser and open DevTools → Console. You should see a log like SeaText initialized or a network request to cdn.seatext.com. In the SeaText dashboard, the "Installation" status will flip to "Active" once the first visitor loads the snippet.

To verify more thoroughly, check the Network tab for a request to api.seatext.com. This confirms the snippet can communicate with SeaText's servers. If you use a content security policy, ensure the required directives are in place (see below).

You can also test locally by running your dev server and opening the browser console. The snippet will execute on localhost, and the dashboard will show the installation as active. This is useful for debugging before you commit to a production deploy.

Common Headless-Specific Gotchas

  • Content Security Policy (CSP): If your site uses a strict CSP, add script-src 'self' https://cdn.seatext.com; and connect-src https://api.seatext.com; to allow the snippet to load and phone home.
  • Hydration mismatches (React/Next.js): The snippet is a plain script tag; it does not participate in React hydration. Place it outside any React-root element (e.g., directly in <head>) to avoid hydration warnings.
  • Dynamic routes / i18n routing: SeaText detects the page URL and visitor language automatically. No extra config is needed for locale-prefixed paths like /en/, /de/.
  • Shadow DOM / Web Components: If your app renders inside a shadow root, SeaText cannot see that content. Mount the snippet in the light DOM (the main document) instead.
  • Client-side routing: In SPAs, the snippet runs once on initial load. You must call window.seatext.rescan() after route changes to apply transformations to new content.
  • Static site generation (SSG): The snippet is added to the HTML output, so it works with pre-rendered pages. No special handling is needed.

If you encounter issues, start by checking the browser console for errors. Common problems include CSP violations, incorrect snippet placement, or the snippet being loaded before the DOM is ready. SeaText's snippet is designed to wait for the DOM, but if you place it in the <head> without defer, it may run too early. The provided snippet includes the necessary attributes, so use it as-is.

Advanced: Triggering Re-scans After Client-Side Navigation

In single-page applications, SeaText runs on the initial load. If you use client-side routing (Next.js Link, React Router, Vue Router), new "pages" don't trigger a full reload. Call window.seatext && window.seatext.rescan() after each route change — for example, in a useEffect hook that watches the router pathname — so SeaText rewrites the new content.

Here is a concrete example for React Router:

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function SeaTextRescan() {
  const location = useLocation();
  useEffect(() => {
    if (window.seatext) {
      window.seatext.rescan();
    }
  }, [location.pathname]);
  return null;
}

For Next.js App Router, you can use the usePathname hook in a client component placed in the root layout. For Vue Router, use a watch on route.fullPath. The key is to call rescan() after the new page's DOM is rendered.

If you use a framework with built-in navigation events (like Nuxt's page:finish), you can hook into those. The goal is to ensure SeaText sees the new content as soon as it appears.

Key Facts

FactDetail
Installation method for non-listed platforms"General / Custom" option in dashboard
Snippet typeAsync JavaScript tag loaded from SeaText CDN
Supported frameworksAny that can output a script tag in the base HTML (Next.js, Astro, Gatsby, Remix, Vite, Hugo, 11ty, custom)
Server-side requirementNone — runs entirely client-side
First activation signalDashboard shows "Active" after first visitor loads snippet
Re-scan for SPA navigationCall window.seatext.rescan() on route change

Limitations & When This Advice Doesn't Apply

  • If your headless backend serves only JSON to a mobile app or third-party frontend, SeaText cannot run there — it needs a browser DOM.
  • Edge middleware (Cloudflare Workers, Vercel Edge Functions) that rewrites HTML before sending to the browser is not required and not supported; the snippet approach is simpler and recommended.
  • Sites with strict CSP that cannot be relaxed will block the snippet unless you add the required directives.
  • If your site uses a service worker to cache pages, the snippet may be cached as well. Ensure the service worker does not strip script tags.
  • For sites that use server-side rendering with streaming (e.g., React Suspense), the snippet may run before all content is streamed. In that case, call rescan() after the stream completes.

These limitations are rare. Most headless sites can install SeaText with the snippet alone. If you hit an edge case, the SeaText support team can help you adapt the integration.

Best Practices for Managing SeaText in a Headless Project

Keep the snippet in a single source of truth. If you use a component library, create a SeaTextSnippet component that you import into your root layout. This makes it easy to update the snippet when SeaText releases changes.

Use environment variables to control the snippet in development vs. production. For example, you might want to disable SeaText in local builds to avoid unnecessary network requests. You can conditionally render the snippet based on process.env.NODE_ENV.

Monitor the dashboard for activation status. If the status stays "Inactive" after deployment, check the browser console for errors. Common causes include a typo in the snippet or a CSP that blocks the CDN.

Test with a staging site before going live. Deploy to a preview URL and verify that SeaText initializes. This catches issues before they affect real visitors.

FAQ

Do I need a separate SeaText project for each locale?

No. One project handles all languages; SeaText detects the visitor's language and translates or rewrites accordingly.

Can I install SeaText via npm instead of a script tag?

The source pack only documents the script-tag method ("General / Custom"). No npm package is mentioned.

Will SeaText slow down my Lighthouse score?

The snippet loads asynchronously from a CDN. Impact is typically under 50 ms; no source-pack benchmarks are provided.

How do I exclude certain pages (e.g., admin dashboards) from SeaText?

Wrap the snippet in a conditional in your layout: only render it when the current path is not an admin route.

What if my site uses a strict Content Security Policy?

Add script-src https://cdn.seatext.com and connect-src https://api.seatext.com to your CSP header or meta tag.

Can I test SeaText locally before deploying?

Yes. Run your dev server (npm run dev), open localhost, and the dashboard will show "Active" once the snippet loads.

Does SeaText work with static site generators like Hugo or 11ty?

Yes. Add the snippet to your base template. The static HTML output will include it, and SeaText will run on the client.

What happens if the SeaText CDN is down?

The snippet fails silently. Your site continues to work normally; SeaText simply does not execute. There is no impact on page rendering.

Can I use SeaText with a headless CMS like Contentful or Sanity?

Yes. The snippet is framework-agnostic. As long as your frontend outputs HTML, SeaText can work with any headless CMS.

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

Further reading and comparison sources

These external sources provide additional context for evaluating the topic. Their inclusion is not an endorsement.

Learn more

Visit the website for more information.

Learn more