Skip to main content
Scripts
NPM

View source

Nuxt Config Setup

Add this to your nuxt.config.ts to load NPM globally. Alternatively you can use the useScriptNpm composable for more control. 

export default defineNuxtConfig({
  scripts: {
    registry: {
      npm: {
        packageName: 'lodash',
        trigger: 'onNuxtReady',
      }
    }
  }
})

This config automatically enables first-party mode (bundle). See below to customise.

useScriptNpm()

The useScriptNpm composable lets you have fine-grain control over when and how NPM is loaded on your site. 

const { proxy } = useScriptNpm()

// loads package from CDN

Please follow the Registry Scripts guide to learn more about advanced usage.

First-Party Mode: Privacy Focused Proxy

No extra config needed. The script is bundled and served from your domain instead of a third-party CDN, eliminating an extra DNS lookup and improving load times. Learn more.

Mode
Bundle 
export default defineNuxtConfig({
  scripts: {
    // ✅ First-party mode: bundled
    registry: {
      npm: {
        packageName: 'lodash',
        trigger: 'onNuxtReady',
      },
    },
  },
})

Example

Using NPM in a component. 

<script setup lang="ts">
const { proxy } = useScriptNpm()

// noop in development, ssr
// just works in production, client
function handleAction() {
  // loads package from CDN
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

Background

You'd usually install an npm package and bundle it with your app. Loading it only when needed takes more work: you need a dynamic import(), a separate chunk, and any required transpilation during the build.

The useScriptNpm() registry script abstracts this process, allowing you to load immediately invoked function expression (IIFE) builds with a single line of code.

Keep frequently used or critical packages in package.json. CDN loading is most useful for an occasional, non-critical IIFE.

The three examples below load the same file through the registry, useScript, and useHead.

useScriptNpm({
  packageName: 'js-confetti',
  file: 'dist/js-confetti.browser.js',
  version: '0.12.0',
  provider: 'jsdelivr',
})

useScriptNpm()

The useScriptNpm() composable uses unpkg by default. Set provider to 'jsdelivr' or 'cdnjs' for the other supported URL formats.

function useScriptNpm<T extends Record<string | symbol, any>>(_options: NpmInput) {}

For triggers, proxying, and other script options, see Registry Scripts.

Map the loaded global

The generic type describes the proxy, but it does not discover a browser global. Map the loaded library explicitly with scriptOptions.use:

interface SomeApi {
  doSomething: () => void
}

const { proxy } = useScriptNpm<SomeApi>({
  packageName: 'some-api',
  scriptOptions: {
    use: () => (window as Window & { SomeApi: SomeApi }).SomeApi,
  },
})

proxy.doSomething()

Without scriptOptions.use, the IIFE still loads, but the composable does not expose its global API through proxy or onLoaded.

packageNamestring required

The npm package name to load.

filestring

The specific file path within the package to load.

versionstring = 'latest'

The package version to load.

provider'jsdelivr' | 'cdnjs' | 'unpkg' = 'unpkg'

The CDN provider to use for loading the package.

Example

See the Tutorial: Load js-confetti for further examples.

Edit this page
Markdown For LLMs

Mixpanel

Load Mixpanel and track product events, identities, profiles, and consent.

PayPal

Load PayPal's JavaScript SDK v6 and create checkout or messaging sessions from Vue components.