Nuxt Waitlist: How to Add Signups to a Nuxt App

Nuxt gives you no index.html to paste a script tag into. That single missing file is where most Nuxt waitlist setups go wrong: the tag ends up in app.vue, where Vue inserts it into the DOM but the browser never executes it, and the form silently renders nothing. The other half end up calling window.OperatorStack.joinWaitlist() in a <script setup> body, and nuxt build dies with window is not defined during prerendering.

Both problems have one-line fixes. This guide covers the correct nuxt.config.ts placement, a signup form with the client guard, the hydration timing rule for <ClientOnly> widgets, and the one kind of Nuxt navigation that page-view tracking misses.

Step 1: Register the Script in nuxt.config.ts

Nuxt builds the document head itself. app.head is the app-wide head config, so anything you put there is emitted into every page Nuxt renders, including routes you have flipped to ssr: false through routeRules.

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: "https://operatorstack.dev/os.js",
          "data-project": "pk_your_project_key",
          tagPosition: "bodyClose",
        },
      ],
    },
  },
});

tagPosition: "bodyClose" puts the tag just before </body>, which is where you want it: the DOM is parsed by the time it runs, so the embed can find your widget containers on its first pass. This is the same file in Nuxt 3 and Nuxt 4. Nuxt 4 moved your source into app/, but nuxt.config.ts stays at the project root either way.

If you would rather keep the config in a component, use useHead instead of raw markup. It routes through the same head system as app.head:

<!-- app/app.vue -->
<script setup lang="ts">
useHead({
  script: [
    {
      src: "https://operatorstack.dev/os.js",
      "data-project": "pk_your_project_key",
      tagPosition: "bodyClose",
    },
  ],
});
</script>

Pick one. Registering the script in both places loads the embed twice.

Step 2: Drop In the Default Widget

For a standard signup form, add the widget div to any page. After the embed initializes it scans the DOM for data-os-widget attributes and renders the form inside a Shadow DOM, so your Tailwind or global CSS cannot collide with it and its styles cannot leak into yours.

<!-- app/pages/index.vue -->
<template>
  <section>
    <h2>Join the waitlist</h2>
    <div data-os-widget="waitlist"></div>
  </section>
</template>

No onMounted, no template ref, no cleanup. This markup is safe to server-render because it is an empty div until the client-side script fills it.

The Hydration Timing Rule

This is the part specific to Nuxt, and it is worth understanding before you wrap anything in <ClientOnly>.

The embed handles the case where your widget container does not exist yet. On startup it checks document.readyState. If the document is still loading it waits for DOMContentLoaded. Otherwise it initializes immediately, and if that first pass finds zero widget containers and zero form containers, it attaches a MutationObserver to document.body and re-initializes as soon as a container appears. That observer disconnects after 10 seconds so it does not leak.

For a server-rendered Nuxt page, none of this matters: your data-os-widget div is in the HTML the server sent, so the first pass finds it. The observer is what covers <ClientOnly> widgets and SPA-mode routes, where the div appears only after Vue hydrates.

Step 3: Build a Custom Form with script setup

When the default widget does not match your design, call the SDK yourself. This is where server rendering starts to matter.

<!-- app/components/WaitlistForm.vue -->
<script setup lang="ts">
const email = ref("");
const loading = ref(false);
const error = ref("");
const shareLinks = ref<{ twitter: string; copy: string } | null>(null);

async function handleSubmit() {
  if (!import.meta.client) return;

  loading.value = true;
  error.value = "";

  try {
    await window.OperatorStack.ready;
    const result = await window.OperatorStack.joinWaitlist({ email: email.value });
    window.OperatorStack.trackEvent("waitlist_signup", { framework: "nuxt" });

    const links = window.OperatorStack.getShareLinks(result.referral_code, {
      text: "I just joined the waitlist, check it out:",
    });
    shareLinks.value = { twitter: links.twitter, copy: links.copy };
  } catch {
    error.value = "Something went wrong. Try again.";
  } finally {
    loading.value = false;
  }
}

function copyLink() {
  if (shareLinks.value) navigator.clipboard.writeText(shareLinks.value.copy);
}
</script>

<template>
  <div v-if="shareLinks">
    <p>You are on the list. Share to move up.</p>
    <a :href="shareLinks.twitter">Share on Twitter</a>
    <button @click="copyLink">Copy referral link</button>
  </div>
  <form v-else @submit.prevent="handleSubmit">
    <input v-model="email" type="email" placeholder="your@email.com" required />
    <button type="submit" :disabled="loading">
      {{ loading ? "Joining..." : "Join waitlist" }}
    </button>
    <p v-if="error" role="alert">{{ error }}</p>
  </form>
</template>

The if (!import.meta.client) return line is the whole server-render fix. import.meta.client is a compile-time constant that Vite replaces with false in the server bundle, so the guard short-circuits and the bundler can drop the window code entirely. Use it rather than process.client, which was the Nuxt 3 spelling and is deprecated.

You do not have to pass a referral code. If the visitor arrived on a ?ref= link, joinWaitlist() reads the stored code and attributes the signup for you. Pass ref explicitly only when you are overriding that.

For TypeScript, declare the global once in a .d.ts at the project root. Nuxt includes root-level declaration files in the generated tsconfig, so no import is needed in components:

// operatorstack.d.ts
declare global {
  interface Window {
    OperatorStack: {
      ready: Promise<void>;
      joinWaitlist: (params: {
        email: string;
        name?: string;
        ref?: string;
      }) => Promise<{ success: boolean; referral_code: string; referral_link: string }>;
      getShareLinks: (
        code: string,
        opts?: { text?: string },
      ) => { twitter: string; linkedin: string; email: string; whatsapp: string; copy: string };
      trackEvent: (name: string, metadata?: Record<string, unknown>) => void;
      getReferralLink: () => { referral_code: string; referral_link: string } | null;
      isSignedUp: () => boolean;
    };
  }
}

export {};

Route Changes Are Tracked, With One Exception

Vue Router calls history.pushState on every push navigation, whether that came from a <NuxtLink> click, a navigateTo() call, or router.push(). The OperatorStack embed patches history.pushState globally and listens for popstate, then schedules a page-view event 100ms later. The delay is a debounce: some routers fire both pushState and popstate for one navigation, and the timer collapses them into a single event. A lastTrackedUrl check drops anything where the URL did not actually change.

Per-route analytics in a Nuxt app costs you zero tracking calls.

<script setup lang="ts">
// Already tracked. No router.afterEach hook needed.
function viewPricing() {
  navigateTo("/pricing");
}
</script>

To keep whole sections out of your analytics, such as an authenticated dashboard, exclude them by path prefix on the script entry:

// nuxt.config.ts
script: [
  {
    src: "https://operatorstack.dev/os.js",
    "data-project": "pk_your_project_key",
    "data-exclude": "/admin,/account",
    tagPosition: "bodyClose",
  },
],

The list is comma-separated and matched as a prefix, so /admin covers /admin/users and everything else beneath it.

Returning Visitors and the Signed-Up State

joinWaitlist() persists the returned referral code to localStorage under a per-project key, so a visitor who already signed up is recognizable on their next visit without you storing anything server-side. That is enough to stop showing a form to someone who already converted.

<script setup lang="ts">
const alreadyJoined = ref(false);

onMounted(async () => {
  await window.OperatorStack.ready;
  alreadyJoined.value = window.OperatorStack.isSignedUp();
});
</script>

<template>
  <p v-if="alreadyJoined">You are already on the list. We will email you at launch.</p>
  <div v-else data-os-widget="waitlist"></div>
</template>

onMounted is the other valid escape hatch alongside import.meta.client. Nuxt never runs it during server rendering, so window is guaranteed to exist inside it. If you want the visitor's own referral link back rather than a boolean, getReferralLink() returns { referral_code, referral_link } or null when they have not signed up.

Common Mistakes

Putting the script tag in a component template. It renders, it sits in the DOM, and it never runs. app.head in nuxt.config.ts or useHead in a component are the two paths that work.

Reaching for onMounted when import.meta.client is simpler. Both work. Use onMounted when you need to read state as the component appears, like the signed-up check above. Use if (!import.meta.client) return inside an event handler, since a submit handler cannot fire on the server anyway and the guard exists to satisfy the build.

Prerendering a route that calls the SDK at module scope. nuxt generate and any route covered by prerender: true in routeRules execute your setup code at build time. Keep SDK calls inside handlers or onMounted and the prerender pass never touches them.

Assuming the widget div needs the SDK. data-os-widget="waitlist" needs zero Vue code and zero guards. Reach for joinWaitlist() only when you want custom UI or need the referral_code back to build a share screen.

Mounting the widget container behind a slow fetch. The embed's re-scan observer gives up after 10 seconds. Render the container up front and toggle its visibility instead of toggling its existence.