Server-Side Rendering Guide

Primer Checkout requires browser APIs and must be loaded on the client side only. This guide shows the patterns for each SSR framework.

Quick Fix

The core pattern is the same for all frameworks—load Primer inside a client-side lifecycle hook:

// Load Primer only on the client
useEffect(() => {
  loadPrimer();
}, []);

That’s it. The sections below show this pattern for each framework.

Next.js

App Router (Recommended)

'use client';

import { useEffect } from 'react';
import { loadPrimer } from '@primer-io/primer-js';

const SDK_OPTIONS = { locale: 'en-GB' };

export default function CheckoutPage() {
  useEffect(() => {
    loadPrimer();
  }, []);

  return (
    <primer-checkout
      client-token="your-client-token"
      options={SDK_OPTIONS}
    />
  );
}

The 'use client' directive marks the component as client-side only.

Pages Router

import { useEffect } from 'react';
import { loadPrimer } from '@primer-io/primer-js';

const SDK_OPTIONS = { locale: 'en-GB' };

export default function CheckoutPage() {
  useEffect(() => {
    if (typeof window !== 'undefined') {
      loadPrimer();
    }
  }, []);

  return (
    <primer-checkout
      client-token="your-client-token"
      options={SDK_OPTIONS}
    />
  );
}

Using next/dynamic (Alternative)

Disable SSR for the entire checkout component:

// components/Checkout.tsx
'use client';

import { useEffect } from 'react';
import { loadPrimer } from '@primer-io/primer-js';

const SDK_OPTIONS = { locale: 'en-GB' };

export function Checkout({ clientToken }: { clientToken: string }) {
  useEffect(() => {
    loadPrimer();
  }, []);

  return (
    <primer-checkout
      client-token={clientToken}
      options={SDK_OPTIONS}
    />
  );
}

// pages/checkout.tsx or app/checkout/page.tsx
import dynamic from 'next/dynamic';

const Checkout = dynamic(
  () => import('@/components/Checkout').then((mod) => mod.Checkout),
  { 
    ssr: false,
    loading: () => <div>Loading checkout...</div>
  }
);

export default function CheckoutPage() {
  return <Checkout clientToken="your-client-token" />;
}

For React 18 vs 19 patterns and handling payment events, see the React Integration Guide.

Nuxt.js

Nuxt 3

<template>
  <div>
    <primer-checkout client-token="your-client-token" />
  </div>
</template>

<script setup>
import { onMounted } from 'vue';

onMounted(async () => {
  if (import.meta.client) {
    const { loadPrimer } = await import('@primer-io/primer-js');
    loadPrimer();
  }
});
</script>

Use import.meta.client in Nuxt 3. The older process.client still works but is a legacy pattern.

Nuxt 2 Pattern

<template>
  <div>
    <primer-checkout client-token="your-client-token" />
  </div>
</template>

<script>
export default {
  mounted() {
    if (process.client) {
      import('@primer-io/primer-js')
        .then(({ loadPrimer }) => {
          loadPrimer();
        })
        .catch((error) => {
          console.error('Failed to load Primer:', error);
        });
    }
  }
}
</script>

SvelteKit

<script>
  import { onMount } from 'svelte';
  import { browser } from '$app/environment';

  onMount(async () => {
    if (browser) {
      const { loadPrimer } = await import('@primer-io/primer-js');
      loadPrimer();
    }
  });
</script>

<primer-checkout client-token="your-client-token" />

Show Loading State

Use the primer:ready event to detect when the checkout is fully initialized:

Next.js
Nuxt 3
SvelteKit

'use client';

import { useEffect, useState, useRef } from 'react';
import { loadPrimer, PrimerCheckoutComponent } from '@primer-io/primer-js';

export default function CheckoutPage() {
  const [isReady, setIsReady] = useState(false);
  const checkoutRef = useRef<PrimerCheckoutComponent>(null);

  useEffect(() => {
    loadPrimer();

    const checkout = checkoutRef.current;
    if (!checkout) return;

    const handleReady = () => setIsReady(true);
    checkout.addEventListener('primer:ready', handleReady);

    return () => checkout.removeEventListener('primer:ready', handleReady);
  }, []);

  return (
    <div>
      {!isReady && <div>Loading payment options...</div>}
      <primer-checkout
        ref={checkoutRef}
        client-token="your-client-token"
        style={{ display: isReady ? 'block' : 'none' }}
      />
    </div>
  );
}

<template>
  <div>
    <div v-if="!isReady">Loading payment options...</div>
    <primer-checkout
      ref="checkoutRef"
      client-token="your-client-token"
      :style="{ display: isReady ? 'block' : 'none' }"
    />
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';

const isReady = ref(false);
const checkoutRef = ref(null);

const handleReady = () => {
  isReady.value = true;
};

onMounted(async () => {
  if (import.meta.client) {
    const { loadPrimer } = await import('@primer-io/primer-js');
    loadPrimer();

    checkoutRef.value?.addEventListener('primer:ready', handleReady);
  }
});

onUnmounted(() => {
  checkoutRef.value?.removeEventListener('primer:ready', handleReady);
});
</script>

<script>
  import { onMount } from 'svelte';
  import { browser } from '$app/environment';

  let isReady = false;
  let checkoutEl;

  onMount(() => {
    if (browser) {
      import('@primer-io/primer-js').then(({ loadPrimer }) => {
        loadPrimer();
      });

      const handleReady = () => {
        isReady = true;
      };

      checkoutEl?.addEventListener('primer:ready', handleReady);

      return () => checkoutEl?.removeEventListener('primer:ready', handleReady);
    }
  });
</script>

<div>
  {#if !isReady}
    <div>Loading payment options...</div>
  {/if}
  <primer-checkout
    bind:this={checkoutEl}
    client-token="your-client-token"
    style:display={isReady ? 'block' : 'none'}
  />
</div>

The primer:ready event fires when the checkout has fully initialized with payment methods. The checkout element must be in the DOM to receive a client token and initialize.

Troubleshooting

”customElements is not defined”

Primer code is running on the server. Fix: Move loadPrimer() inside a client-side lifecycle hook (useEffect, onMounted, onMount).

“window is not defined”

Code is accessing browser globals during SSR. Fix: Add an environment check:

if (typeof window !== 'undefined') {
  // Browser-only code
}

Components Don’t Render

The checkout needs a valid client token to initialize. Fix: Ensure you’re passing a valid client-token attribute. Use the primer:ready event to detect when initialization is complete. See Show Loading State above.

TypeScript Errors

TypeScript doesn’t recognize <primer-checkout> as a valid element. Fix: Add type declarations:

// src/types/primer.d.ts
import { CustomElements } from '@primer-io/primer-js/dist/jsx/index';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements extends CustomElements {}
  }
}

Why SSR Needs This

Technical explanation

Server-side rendering frameworks execute code on the server to generate HTML before sending it to the browser. Primer Checkout depends on browser-only APIs:

Web Components API – customElements.define() only exists in browsers
DOM APIs – Component rendering requires the Document Object Model
Window Object – Payment features depend on window and browser globals
Secure Iframes – Card inputs require a browser environment

When SSR frameworks try to execute Primer code on the server, they encounter errors because these APIs don’t exist in Node.js. The solution is to ensure Primer only loads on the client side using lifecycle hooks that run after hydration.

Checkout

Server-Side Rendering Guide

Quick Fix

Next.js

App Router (Recommended)

Pages Router

Using next/dynamic (Alternative)

Nuxt.js

Nuxt 3

SvelteKit

Show Loading State

Troubleshooting

”customElements is not defined”

“window is not defined”

Components Don’t Render

TypeScript Errors

Why SSR Needs This

Next Steps

React Integration

Styling

Events Guide

Troubleshooting

​Quick Fix

​Next.js

​App Router (Recommended)

​Pages Router

​Using next/dynamic (Alternative)

​Nuxt.js

​Nuxt 3

​SvelteKit

​Show Loading State

​Troubleshooting

​”customElements is not defined”

​“window is not defined”

​Components Don’t Render

​TypeScript Errors

​Why SSR Needs This

​Next Steps

React Integration

Styling

Events Guide

Troubleshooting

Quick Fix

Next.js

App Router (Recommended)

Pages Router

Using next/dynamic (Alternative)

Nuxt.js

Nuxt 3

SvelteKit

Show Loading State

Troubleshooting

”customElements is not defined”

“window is not defined”

Components Don’t Render

TypeScript Errors

Why SSR Needs This

Next Steps