In Nuxt 4, where and how often does a `defineNuxtPlugin` plugin run, and how do you load an analytics client only in the browser and expose `$track`?

## What a Nuxt plugin is A Nuxt plugin is a file that runs **while the Nuxt application is created**, before the root component renders. It receives `nuxtApp`, the Nuxt application instance, and can register runtime hooks, install Vue plugins through `nuxtApp.vueApp.use(...)`, and provide helpers to the rest of the app. ```ts export default defineNuxtPlugin((nuxtApp) => { // runs at app creation }) ``` ## Where plugins come from - **`app/plugins/`**: files at the top level are registered automatically. An `index` file inside a subfolder is still scanned but deprecated; other nested files are not, and must be listed in the `plugins` option of `nuxt.config.ts`. - **Modules**: `addPlugin` from `@nuxt/kit`, which puts module plugins before the app's own. ## When and where they run | Environment | How often | Notes | |---|---|---| | Server (SSR) | once per request | each request gets a fresh Nuxt app | | Browser | once per page load | before hydration starts | | `.client` file | browser only | never part of the server render | | `.server` file | server only | never shipped to the browser bundle | Two consequences follow. A plugin without a suffix must be safe on both sides; code touching `window` belongs in a `.client` plugin. And because the server runs plugins per request, expensive work there is paid on every render. ## Order Plugins run **sequentially** by default: 1. Module plugins, then the app's plugins in file-name order, sorted as strings, so `10.a.ts` comes before `2.b.ts`; pad numbers as `01.`, `02.`. 2. The object form can move a plugin with `enforce: 'pre'` or `'post'`, or a numeric `order` for fine control. 3. `dependsOn: ['name']` makes a plugin wait for named plugins; `parallel: true` lets the next plugin start without waiting. The object form also takes `name`, `setup` and `hooks`. Nuxt analyses these properties statically, so do not compute them at runtime. ## Providing `$track` Returning a `provide` object exposes helpers with a `$` prefix on `nuxtApp` and in templates: - `return { provide: { track } }` gives `useNuxtApp().$track(...)` in script code and `$track(...)` in templates. - Provided values are typed automatically from the return value. For the analytics module, a browser-only plugin loads the client, provides `$track`, and records page views on the `page:finish` runtime hook, which Nuxt calls when a page component has finished loading. ## The server side of a client-only helper If `$track` comes from a `.client` plugin, it does not exist while the server renders. Code that calls it in `<script setup>` during SSR fails. Three ways to handle it: - call `$track` only from event handlers or `onMounted`, which do not run on the server; - add a small `analytics.server.ts` that provides a no-op `track`, so both sides have the helper; - guard with `if (import.meta.client)`. ## Limits worth knowing - Plugins can call composables such as `useRuntimeConfig()` and `useRouter()`, but not Vue lifecycle composables, because a plugin is bound to `nuxtApp`, not to a component. - A composable that depends on a later plugin may not work yet. - A plugin that reads a private runtime key and provides it as a helper would put the key in the browser if the plugin ran there; keep secrets in server code. ## Choosing between a plugin and other extension points | Need | Use | |---|---| | run once as the app starts, provide a helper, register app hooks | a Nuxt plugin | | a reusable function a component calls | a composable (auto-imported from `composables/` or added by a module) | | code on every server request, before routes | Nitro server middleware | | change build output or register files | a module | A plugin is the right place for the analytics client because it must exist once per app, before any page asks for `$track`. A composable such as `useTrackEvent` can then wrap `useNuxtApp().$track` for components, which keeps the provided name an implementation detail. ## Performance note Plugins delay the app: Nuxt waits for all of them, parallel ones included, before it goes on to render. `parallel: true` only lets independent async plugins overlap instead of queueing. Keep plugin setup cheap, mark independent async plugins parallel, and load heavy SDKs lazily, for example with a dynamic `import()` inside the first `track` call.