Skip to main content
This guide covers how to install Userplane in a Nuxt 3 application.

​
Adding the script

The fastest way to add Userplane is the CDN embed. Add these two tags to the <head> in nuxt.config.ts: 
// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      meta: [{ name: 'userplane:workspace', content: 'YOUR_WORKSPACE_ID' }],
      script: [{ type: 'module', src: 'https://cdn.userplane.io/embed/script.js' }],
    },
  },
});
You can copy the snippet with your workspace ID pre-filled from Workspace Settings > Domains in the Userplane dashboard.

​
npm SDK

Use the npm SDK when you need programmatic control — triggering recordings from a button, attaching user metadata, or reading recording state.

​
Installation

npm install @userplane/sdk

​
Initialization

Create a plugin file with the .client.ts suffix. Nuxt only runs .client.ts plugins in the browser, so no additional SSR guard is needed. 
// plugins/userplane.client.ts
export default defineNuxtPlugin(async () => {
  const { initialize } = await import('@userplane/sdk');
  const config = useRuntimeConfig();

  initialize({
    workspaceId: config.public.userplaneWorkspaceId,
  });
});
Expose the workspace ID through Nuxt’s runtime config so it is available on both server and client: 
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      userplaneWorkspaceId: '',
    },
  },
});
Set the value in your .env file: 
NUXT_PUBLIC_USERPLANE_WORKSPACE_ID=ws_abc123
Nuxt automatically maps NUXT_PUBLIC_* environment variables to runtimeConfig.public.*.

​
URL parameters

When a customer opens a recording link, Userplane appends userplane-token and userplane-action to the URL. If your app uses Nuxt middleware to redirect unauthenticated users, preserve the userplane- prefixed parameters through the redirect: 
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  if (!isAuthenticated()) {
    const query: Record<string, string> = {};

    for (const [key, value] of Object.entries(to.query)) {
      if (key.startsWith('userplane-') && typeof value === 'string') {
        query[key] = value;
      }
    }

    return navigateTo({ path: '/login', query });
  }
});
See Installation for the full list of parameters.

​
Sensitive data

Add data-userplane-blur to any element you want blurred in recordings. See Sensitive Data Redaction for the full reference.

​
Metadata

Call set() inside the plugin after initialize(): 
// plugins/userplane.client.ts
export default defineNuxtPlugin(async () => {
  const { initialize, set } = await import('@userplane/sdk');
  const config = useRuntimeConfig();

  initialize({ workspaceId: config.public.userplaneWorkspaceId });
  set('environment', 'production');
});
See Metadata SDK for the full API.

​
SSR

The .client.ts suffix tells Nuxt to exclude this plugin from the server bundle entirely. You do not need ssr: false in nuxt.config.ts or any process.client guards inside the plugin. @userplane/sdk is SSR-safe to import — it does not reference window or document at module evaluation time. The dynamic import('@userplane/sdk') inside the plugin is an optional optimization; a static import also works.
ConcernSafe?Notes
.client.ts plugin suffixYesNuxt excludes file from SSR bundle
Static import inside .client.tsYesFile never runs on server
Dynamic import('@userplane/sdk')YesBundle-size optimization only
Calling initialize() in a server pluginNowindow is not available

​
Example app

A complete Nuxt 3 example is available at github.com/wizenheimer/userplane-sdk-examples/tree/main/examples/nuxt.
VariableDescription
NUXT_PUBLIC_USERPLANE_WORKSPACE_IDYour Userplane workspace ID
cd examples/nuxt && npm install && npm run dev