Seatext library

How to Troubleshoot SeaText AI Not Working in Your Single-Page Application

Start by opening the browser console and network tab to confirm the SeaText script loads without errors. Verify the snippet sits in your index.html before the app mounts, and check that local storage and...

Prerequisites for SPA Integration

Before you troubleshoot, confirm your environment meets the baseline requirements. SeaText AI loads asynchronously via a script tag with the async attribute, so it will not block page rendering. The script writes an identifier to localStorage; your application must permit local storage access in all target browsers. If your SPA serves content from multiple domains or subdomains, ensure the script can operate across those origins without being blocked by CORS policies.

You also need a clear entry point. In most SPAs this is index.html or the main JavaScript/TypeScript file where the framework boots (for example main.tsx in React, main.js in Vue, or main.ts in Angular). The SeaText snippet must be placed inside the <body> of that entry HTML or in the equivalent bootstrap section of your framework.

Step-by-Step Troubleshooting Checklist

Open Developer Tools. Press F12, switch to the Console tab, and reload the page. Look for red error messages that reference seatext or the script URL.
Check the Network tab. Filter for JS files and confirm the SeaText script returns HTTP 200. A 404 or 403 means the snippet URL is wrong or blocked by a proxy.
Verify script placement. View the page source and ensure the snippet appears inside <body> before your framework’s root element mounts. If you injected the snippet via a package manager or build plugin, confirm the build output includes it in the final HTML.
Test local storage. In the console run localStorage.setItem('test', '1'). If it throws a security error, your SPA runs in a sandbox (e.g., an iframe with sandbox attribute) that blocks storage. SeaText will fail silently in that case.
Inspect cross-origin requests. If your SPA loads assets from a CDN or separate API domain, open the Network tab and check for CORS errors on the SeaText script request. The script must be served with Access-Control-Allow-Origin headers that include your SPA’s origin.
Confirm configuration object. SeaText expects a global configuration object (often window.seatextConfig) before the script executes. Verify the object exists and matches the keys documented in the SeaText integration guide.
Rebuild and serve. Run your framework’s standard dev command (npm start, npm run serve, ng serve) and repeat steps 1–2. A production build (npm run build then serve the dist folder) can surface minification or chunk-loading issues that don’t appear in dev mode.
Functionality check. Once the script loads cleanly, trigger a SeaText feature (for example, a translation or variant test) and verify the DOM updates as expected.

Common Integration Mistakes

Placing the snippet in <head>. The documentation specifies <body> placement; head placement can cause the script to execute before the DOM is ready, breaking DOM-dependent features.
Using a bundler that strips async. Some build tools inline or defer scripts differently. Ensure the final HTML still contains <script async src="..."></script>.
Overwriting localStorage keys. If your app clears local storage on login or route change, SeaText loses its identifier and resets on every navigation.
Content Security Policy (CSP) blocking inline scripts. SeaText’s snippet is external, but if your CSP includes script-src 'self' without the SeaText domain, the script will be blocked. Add the SeaText CDN origin to your CSP.
Multiple SeaText instances. Including the snippet in both a layout component and index.html loads the script twice, causing race conditions.

Framework-Specific Guidance

React

In a Create React App or Vite project, paste the snippet into public/index.html inside <body> before <div id="root"></div>. If you use Next.js, add the script to pages/_document.js (Pages Router) or app/layout.tsx with <Script strategy="beforeInteractive" src="..." /> (App Router). After editing, run npm start and verify the console shows no SeaText errors.

Vue.js

For Vue CLI projects, edit public/index.html the same way. In Vite-based Vue apps, the entry HTML is index.html at the project root. If you use Nuxt, add the script via head.script in nuxt.config.ts with tagPosition: 'bodyOpen'. Run npm run dev and check the Network tab for the script load.

Angular

Angular CLI projects use src/index.html. Insert the snippet just before the closing </body> tag. For Angular Universal (SSR), the script must also be present in the server-rendered HTML; add it to server/index.html or use Domino to inject it during server rendering. Run ng serve and confirm the script appears in the browser’s Network waterfall.

Verification Step

After completing the checklist, perform a single end-to-end verification: open the SPA in an incognito window, trigger a SeaText-driven change (for example, switch the UI language or load a test variant), and confirm the change persists after a soft reload (F5). If the change appears and survives reload, the integration is working. If not, revisit the console for new errors and repeat the relevant steps.

Key Facts

Aspect	Detail
Script loading	Asynchronous via `async` attribute
Storage requirement	Uses `localStorage` for an identifier
Cross-origin	Must allow script execution across all SPA domains
Entry point	`index.html` or framework bootstrap file
Snippet placement	Inside `<body>` before app mount
Dev commands	`npm start`, `npm run serve`, `ng serve`
Verification tools	Browser Console and Network tabs (F12)

Limitations and When This Advice Does Not Apply

This troubleshooting guide covers client-side SPA integration only. It does not address server-side rendering hydration mismatches, native mobile wrappers (Capacitor, React Native WebView), or environments where JavaScript is disabled. If your SPA runs inside a restricted iframe, a browser extension, or a headless CMS preview that strips third-party scripts, the steps above will not resolve the issue. In those cases, consult SeaText support with a HAR file of the failed load.

Terminology

SPA (Single-Page Application): A web app that loads a single HTML page and dynamically updates content via JavaScript without full page reloads.
Entry point: The HTML or JavaScript file where the application bootstrap begins.
Async script: A script tag with the async attribute that downloads in parallel and executes as soon as it’s ready.
localStorage: A browser API for persisting key-value pairs across sessions; requires user permission in some privacy modes.
CORS (Cross-Origin Resource Sharing): A browser security mechanism that controls whether a page can request resources from a different origin.

FAQ

Why does SeaText work in development but break after a production build?

Production builds often minify HTML, change script loading order, or apply CSP headers that differ from dev. Re-run the checklist against the built dist or build folder served by a static server.

Can I load SeaText dynamically via `import()` instead of a script tag?

The official snippet is designed for direct HTML inclusion. Dynamic import may work but is unsupported; you lose the async loading guarantee and local storage initialization timing.

What if my SPA uses a micro-frontend architecture?

Each micro-frontend that needs SeaText must include the snippet in its own entry HTML, or you must ensure the host app loads the script once and exposes the SeaText API globally to all children.

How do I know the script URL is correct?

The snippet provided in the SeaText dashboard contains the current CDN URL. Copy it exactly; do not host the script yourself unless instructed by SeaText support.

Does SeaText work with strict CSP `script-src 'self'`?

No. You must add the SeaText CDN origin (e.g., https://cdn.seatext.com) to your script-src directive.

What should I send to support if nothing works?

Provide a HAR export from the Network tab, the exact snippet you pasted, your framework and version, and a minimal reproduction repo if possible.

How SeaText can help

SeaText AI rewrites headlines, offers, and calls to action in real time for each paid click, translates pages into 125 languages, and detects bot traffic to build refund-ready reports for Google and Meta. The SPA integration uses a single asynchronous script that stores a lightweight identifier in local storage. If your SPA meets the prerequisites — local storage access, permissive CSP, and correct snippet placement — the integration activates without additional code. The main limitation is that environments blocking third-party scripts or local storage (strict iframes, some browser privacy modes) will prevent SeaText from initializing.

Start a free 1-month pilot