Registry Scripts

Registry scripts enhance the developer experience by simplifying the integration of third-party scripts in Nuxt Scripts.

For the list of supported registry scripts, see the Script Registry list.

Features

😌 Safe Initialization

Many third-party scripts require initialing some global state before loading the script, Nuxt Scripts handles this for you in an optimized way.

🏎️ Fine-grain performance tuning

Each registry script has been optimized to load the script functionality in the most efficient way possible.

📜 Fully Typed

Handling third-party scripts usually means dealing with their API types on your own. Registry scripts alleviate this by providing predefined types, enabling code completion and type safety in your projects.

✅ Validating Options

Using Valibot, registry scripts automatically validate the configuration options of third-party scripts, helping you identify and resolve misconfigurations early. For instance, they check the token length for Cloudflare Web Analytics.

export const CloudflareWebAnalyticsOptions = object({
  /**
   * The Cloudflare Web Analytics token.
   */
  token: string([minLength(32)]),
  /**
   * Cloudflare Web Analytics enables measuring SPAs automatically by overriding the History API’s pushState function
   * and listening to the onpopstate. Hash-based router is not supported.
   *
   * @default true
   */
  spa: optional(boolean()),
})

For performance reasons, validation will only occur during development. It will be tree-shaken out of your production build.

🤫 Runtime Config Integration

Registry scripts can be configured through your .env file, allowing you to provide script options without hardcoding them in your codebase.

NUXT_SCRIPTS_CLOUDFLARE_WEB_ANALYTICS=YOUR_TOKEN

Usage

Disabling in development

When you want to use the exposed API script in development, say calling gtag in a component, you want to load a mocked version of the script, so that it will never load.

You can do this by providing a mock value to the registry script.

export default defineNuxtConfig({
  scripts: {
    registry: {
      googleTagManager: true,
    },
  },
  $development: {
    scripts: {
      registry: {
        googleTagManager: "mock",
      },
    },
  },
})

Loading multiple of the same script

You may have a setup where you need to load the same registry script multiple times using different configuration.

By default, they will be deduped and only loaded once, to load multiple instances of the same script, you can provide a unique key to the script.

const { gtag, $script } = useScriptGoogleAnalytics({
  id: 'G-TR58L0EF8P',
})

const { gtag: gtag2, $script: $script2 } = useScriptGoogleAnalytics({
  // without a key the first script instance will be returned
  key: 'gtag2',
  id: 'G-1234567890',
})

It's important to note that when modifying the key, any environment variables you're using will break.

For example, with gtag2 as the key, you'd need to provide runtime config as following:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      scripts: {
        gtag2: {
          id: '', // NUXT_PUBLIC_SCRIPTS_GTAG2_ID
        },
      },
    },
  },
})

Using Script Options and Script Input

Registry scripts doesn't stop you from making use of the core useScript features, you can provide extra options to opt-in to the advanced features.

• scriptOptions - Additional options to pass to the script. Same as useScript Options.
• scriptInput - Additional input to pass to the script. Same as useScript Input.

import { useTimeout } from '@vueuse/core'
import { useScriptCloudflareWebAnalytics } from '#imports'

const { ready } = useTimeout(5000)
useScriptCloudflareWebAnalytics({
  token: '123',
  // HTML attributes to pass to the script element
  scriptInput: {
    'data-cf-test': 'true'
  },
  // useScript options used for advanced features
  scriptOptions: {
    trigger: ready,
    bundle: true,
  },
})

Loading best practices

When using a registry script in multiple pages or components, it's recommended to either initialize the script in your app.vue or your nuxt.config with the required options.

Any subsequent calls to the registry script will use the same instance of the script, not requiring any options.

export default defineNuxtConfig({
  scripts: {
    registry: {
      // loads the script
      fathomAnalytics: {
        site: 'SITE_ID',
      }
    }
  }
})

Alternatively you can wrap the registry script in a composable to allow for easier instantiation of the script.

export function useFathomAnalytics() {
  return useScriptFathomAnalytics({
    site: 'SITE_ID',
  })
}