From 2d0ff9f3d6d2f4201ec4d94f28c7b64b7330375f Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 18 Mar 2026 17:19:19 +1100
Subject: [PATCH 1/3] fix: improve registry script DX and type safety

- Make all schema fields Partial in RegistryScriptInput so composables
  don't require config when provided via runtime config / env vars
- Drop CanBypassOptions type param (no longer needed)
- Fix merge order: use defu instead of Object.assign so composable
  args take priority over runtime config
- Add false to NuxtConfigScriptRegistryEntry for explicit disable
- Skip false entries in module registry processing
---
 src/module.ts                            |  3 +++
 src/runtime/registry/bluesky-embed.ts    |  2 +-
 src/runtime/registry/crisp.ts            |  2 +-
 src/runtime/registry/fathom-analytics.ts |  2 +-
 src/runtime/registry/google-adsense.ts   |  2 +-
 src/runtime/registry/hotjar.ts           |  2 +-
 src/runtime/registry/instagram-embed.ts  |  2 +-
 src/runtime/registry/intercom.ts         |  2 +-
 src/runtime/registry/matomo-analytics.ts |  2 +-
 src/runtime/registry/meta-pixel.ts       |  2 +-
 src/runtime/registry/npm.ts              |  2 +-
 src/runtime/registry/reddit-pixel.ts     |  2 +-
 src/runtime/registry/snapchat-pixel.ts   |  2 +-
 src/runtime/registry/tiktok-pixel.ts     |  2 +-
 src/runtime/registry/vercel-analytics.ts |  2 +-
 src/runtime/registry/x-embed.ts          |  2 +-
 src/runtime/registry/x-pixel.ts          |  2 +-
 src/runtime/types.ts                     | 30 ++++++++----------------
 src/runtime/utils.ts                     |  2 +-
 19 files changed, 30 insertions(+), 37 deletions(-)

diff --git a/src/module.ts b/src/module.ts
index 17b188b4a..9d34d0aba 100644
--- a/src/module.ts
+++ b/src/module.ts
@@ -343,6 +343,9 @@ export default defineNuxtModule<ModuleOptions>({
       // NUXT_PUBLIC_SCRIPTS_<SCRIPT>_<KEY> works without manual runtimeConfig
       const registryWithDefaults: Record<string, any> = {}
       for (const [key, value] of Object.entries(config.registry)) {
+        if (value === false) {
+          continue
+        }
         if (value && REGISTRY_ENV_DEFAULTS[key]) {
           const envDefaults = REGISTRY_ENV_DEFAULTS[key]
           if (value === true || value === 'mock') {
diff --git a/src/runtime/registry/bluesky-embed.ts b/src/runtime/registry/bluesky-embed.ts
index e12bf73a5..3a3cd6034 100644
--- a/src/runtime/registry/bluesky-embed.ts
+++ b/src/runtime/registry/bluesky-embed.ts
@@ -71,7 +71,7 @@ export interface BlueskyEmbedPostData {
   labels: Array<{ val: string }>
 }
 
-export type BlueskyEmbedInput = RegistryScriptInput<typeof BlueskyEmbedOptions, false, false, false>
+export type BlueskyEmbedInput = RegistryScriptInput<typeof BlueskyEmbedOptions, false, false>
 
 const BSKY_POST_URL_RE = /bsky\.app\/profile\/([^/]+)\/post\/([^/?]+)/
 
diff --git a/src/runtime/registry/crisp.ts b/src/runtime/registry/crisp.ts
index 630ddf8b1..f0a935dcc 100644
--- a/src/runtime/registry/crisp.ts
+++ b/src/runtime/registry/crisp.ts
@@ -4,7 +4,7 @@ import { CrispOptions } from './schemas'
 
 export { CrispOptions }
 
-export type CrispInput = RegistryScriptInput<typeof CrispOptions, false, false, false>
+export type CrispInput = RegistryScriptInput<typeof CrispOptions, false, false>
 
 export interface CrispApi {
   push: (...args: any[]) => void
diff --git a/src/runtime/registry/fathom-analytics.ts b/src/runtime/registry/fathom-analytics.ts
index 998aa361b..29d7bde32 100644
--- a/src/runtime/registry/fathom-analytics.ts
+++ b/src/runtime/registry/fathom-analytics.ts
@@ -4,7 +4,7 @@ import { FathomAnalyticsOptions } from './schemas'
 
 export { FathomAnalyticsOptions }
 
-export type FathomAnalyticsInput = RegistryScriptInput<typeof FathomAnalyticsOptions, false, false, false>
+export type FathomAnalyticsInput = RegistryScriptInput<typeof FathomAnalyticsOptions, false, false>
 
 export interface FathomAnalyticsApi {
   beacon: (ctx: { url: string, referrer?: string }) => void
diff --git a/src/runtime/registry/google-adsense.ts b/src/runtime/registry/google-adsense.ts
index 0efbd8f92..48da86617 100644
--- a/src/runtime/registry/google-adsense.ts
+++ b/src/runtime/registry/google-adsense.ts
@@ -5,7 +5,7 @@ import { GoogleAdsenseOptions } from './schemas'
 
 export { GoogleAdsenseOptions }
 
-export type GoogleAdsenseInput = RegistryScriptInput<typeof GoogleAdsenseOptions, true, false, false>
+export type GoogleAdsenseInput = RegistryScriptInput<typeof GoogleAdsenseOptions, true, false>
 
 export interface GoogleAdsenseApi {
   /**
diff --git a/src/runtime/registry/hotjar.ts b/src/runtime/registry/hotjar.ts
index 5ba872b22..9ce6dc5c0 100644
--- a/src/runtime/registry/hotjar.ts
+++ b/src/runtime/registry/hotjar.ts
@@ -16,7 +16,7 @@ declare global {
   }
 }
 
-export type HotjarInput = RegistryScriptInput<typeof HotjarOptions, true, false, false>
+export type HotjarInput = RegistryScriptInput<typeof HotjarOptions, true, false>
 
 export function useScriptHotjar<T extends HotjarApi>(_options?: HotjarInput) {
   return useRegistryScript<T, typeof HotjarOptions>('hotjar', options => ({
diff --git a/src/runtime/registry/instagram-embed.ts b/src/runtime/registry/instagram-embed.ts
index 8f2b58278..00c88b6e2 100644
--- a/src/runtime/registry/instagram-embed.ts
+++ b/src/runtime/registry/instagram-embed.ts
@@ -3,7 +3,7 @@ import { InstagramEmbedOptions } from './schemas'
 
 export { InstagramEmbedOptions }
 
-export type InstagramEmbedInput = RegistryScriptInput<typeof InstagramEmbedOptions, false, false, false>
+export type InstagramEmbedInput = RegistryScriptInput<typeof InstagramEmbedOptions, false, false>
 
 const INSTAGRAM_SHORTCODE_RE = /instagram\.com\/(?:p|reel|tv)\/([^/?]+)/
 
diff --git a/src/runtime/registry/intercom.ts b/src/runtime/registry/intercom.ts
index 88897ecfc..dd0a7c5fb 100644
--- a/src/runtime/registry/intercom.ts
+++ b/src/runtime/registry/intercom.ts
@@ -6,7 +6,7 @@ import { IntercomOptions } from './schemas'
 
 export { IntercomOptions }
 
-export type IntercomInput = RegistryScriptInput<typeof IntercomOptions, true, false, false>
+export type IntercomInput = RegistryScriptInput<typeof IntercomOptions, true, false>
 
 export interface IntercomApi {
   Intercom: ((event: 'boot', data?: InferInput<typeof IntercomOptions>) => void)
diff --git a/src/runtime/registry/matomo-analytics.ts b/src/runtime/registry/matomo-analytics.ts
index 00b9be8bd..b285008c2 100644
--- a/src/runtime/registry/matomo-analytics.ts
+++ b/src/runtime/registry/matomo-analytics.ts
@@ -7,7 +7,7 @@ import { MatomoAnalyticsOptions } from './schemas'
 
 export { MatomoAnalyticsOptions }
 
-export type MatomoAnalyticsInput = RegistryScriptInput<typeof MatomoAnalyticsOptions, false, false, false>
+export type MatomoAnalyticsInput = RegistryScriptInput<typeof MatomoAnalyticsOptions, false, false>
 
 interface MatomoAnalyticsApi {
   _paq: unknown[]
diff --git a/src/runtime/registry/meta-pixel.ts b/src/runtime/registry/meta-pixel.ts
index 07ee387f8..96a298d5e 100644
--- a/src/runtime/registry/meta-pixel.ts
+++ b/src/runtime/registry/meta-pixel.ts
@@ -48,7 +48,7 @@ declare global {
 }
 
 export { MetaPixelOptions }
-export type MetaPixelInput = RegistryScriptInput<typeof MetaPixelOptions, true, false, false>
+export type MetaPixelInput = RegistryScriptInput<typeof MetaPixelOptions, true, false>
 
 export function useScriptMetaPixel<T extends MetaPixelApi>(_options?: MetaPixelInput) {
   return useRegistryScript<T, typeof MetaPixelOptions>('metaPixel', options => ({
diff --git a/src/runtime/registry/npm.ts b/src/runtime/registry/npm.ts
index b15d63d57..06d7c4d0e 100644
--- a/src/runtime/registry/npm.ts
+++ b/src/runtime/registry/npm.ts
@@ -7,7 +7,7 @@ export { NpmOptions }
 
 type Provider = 'jsdelivr' | 'cdnjs' | 'unpkg'
 
-export type NpmInput = RegistryScriptInput<typeof NpmOptions, true, true, false>
+export type NpmInput = RegistryScriptInput<typeof NpmOptions, true, true>
 
 export function useScriptNpm<T extends Record<string | symbol, any>>(_options: NpmInput) {
   return useRegistryScript<T, typeof NpmOptions>(`${_options.packageName}-npm`, (options) => {
diff --git a/src/runtime/registry/reddit-pixel.ts b/src/runtime/registry/reddit-pixel.ts
index 8d0227c26..9aadf179d 100644
--- a/src/runtime/registry/reddit-pixel.ts
+++ b/src/runtime/registry/reddit-pixel.ts
@@ -21,7 +21,7 @@ declare global {
 }
 
 export { RedditPixelOptions }
-export type RedditPixelInput = RegistryScriptInput<typeof RedditPixelOptions, true, false, false>
+export type RedditPixelInput = RegistryScriptInput<typeof RedditPixelOptions, true, false>
 
 export function useScriptRedditPixel<T extends RedditPixelApi>(_options?: RedditPixelInput) {
   return useRegistryScript<T, typeof RedditPixelOptions>('redditPixel', (options) => {
diff --git a/src/runtime/registry/snapchat-pixel.ts b/src/runtime/registry/snapchat-pixel.ts
index f03149710..17f32aacd 100644
--- a/src/runtime/registry/snapchat-pixel.ts
+++ b/src/runtime/registry/snapchat-pixel.ts
@@ -49,7 +49,7 @@ export interface SnapPixelApi {
 declare global {
   interface Window extends SnapPixelApi {}
 }
-export type SnapTrPixelInput = RegistryScriptInput<typeof SnapTrPixelOptions, true, false, false>
+export type SnapTrPixelInput = RegistryScriptInput<typeof SnapTrPixelOptions, true, false>
 
 export function useScriptSnapchatPixel<T extends SnapPixelApi>(_options?: SnapTrPixelInput) {
   return useRegistryScript<T, typeof SnapTrPixelOptions>('snapchatPixel', options => ({
diff --git a/src/runtime/registry/tiktok-pixel.ts b/src/runtime/registry/tiktok-pixel.ts
index 4a07f80ab..9521e31c2 100644
--- a/src/runtime/registry/tiktok-pixel.ts
+++ b/src/runtime/registry/tiktok-pixel.ts
@@ -59,7 +59,7 @@ declare global {
 
 export { TikTokPixelOptions }
 
-export type TikTokPixelInput = RegistryScriptInput<typeof TikTokPixelOptions, true, false, false>
+export type TikTokPixelInput = RegistryScriptInput<typeof TikTokPixelOptions, true, false>
 
 export function useScriptTikTokPixel<T extends TikTokPixelApi>(_options?: TikTokPixelInput) {
   return useRegistryScript<T, typeof TikTokPixelOptions>('tiktokPixel', options => ({
diff --git a/src/runtime/registry/vercel-analytics.ts b/src/runtime/registry/vercel-analytics.ts
index cd02b256f..da1466b45 100644
--- a/src/runtime/registry/vercel-analytics.ts
+++ b/src/runtime/registry/vercel-analytics.ts
@@ -15,7 +15,7 @@ export interface BeforeSendEvent {
 
 export type BeforeSend = (event: BeforeSendEvent) => BeforeSendEvent | null
 
-export type VercelAnalyticsInput = RegistryScriptInput<typeof VercelAnalyticsOptions, false, false, false> & {
+export type VercelAnalyticsInput = RegistryScriptInput<typeof VercelAnalyticsOptions, false, false> & {
   beforeSend?: BeforeSend
 }
 
diff --git a/src/runtime/registry/x-embed.ts b/src/runtime/registry/x-embed.ts
index 45aecd4bc..17318c5b9 100644
--- a/src/runtime/registry/x-embed.ts
+++ b/src/runtime/registry/x-embed.ts
@@ -45,7 +45,7 @@ export interface XEmbedTweetData {
   }
 }
 
-export type XEmbedInput = RegistryScriptInput<typeof XEmbedOptions, false, false, false>
+export type XEmbedInput = RegistryScriptInput<typeof XEmbedOptions, false, false>
 
 /**
  * Proxy an X/Twitter image URL through the server
diff --git a/src/runtime/registry/x-pixel.ts b/src/runtime/registry/x-pixel.ts
index b40c87a0a..240e5e123 100644
--- a/src/runtime/registry/x-pixel.ts
+++ b/src/runtime/registry/x-pixel.ts
@@ -40,7 +40,7 @@ declare global {
 }
 
 export { XPixelOptions }
-export type XPixelInput = RegistryScriptInput<typeof XPixelOptions, true, false, false>
+export type XPixelInput = RegistryScriptInput<typeof XPixelOptions, true, false>
 
 export function useScriptXPixel<T extends XPixelApi>(_options?: XPixelInput) {
   return useRegistryScript<T, typeof XPixelOptions>('xPixel', (options) => {
diff --git a/src/runtime/types.ts b/src/runtime/types.ts
index b4789f9b6..827d4a9d0 100644
--- a/src/runtime/types.ts
+++ b/src/runtime/types.ts
@@ -196,7 +196,7 @@ export interface ScriptRegistry {
   [key: `${string}-npm`]: NpmInput
 }
 
-export type NuxtConfigScriptRegistryEntry<T> = true | 'mock' | T | [T, NuxtUseScriptOptionsSerializable]
+export type NuxtConfigScriptRegistryEntry<T> = true | false | 'mock' | T | [T, NuxtUseScriptOptionsSerializable]
 export type NuxtConfigScriptRegistry<T extends keyof ScriptRegistry = keyof ScriptRegistry> = Partial<{
   [key in T]: NuxtConfigScriptRegistryEntry<ScriptRegistry[key]>
 }> & Record<string & {}, NuxtConfigScriptRegistryEntry<any>>
@@ -216,26 +216,16 @@ export type RegistryScriptInput<
   T = EmptyOptionsSchema,
   Bundelable extends boolean = true,
   Usable extends boolean = false,
-  CanBypassOptions extends boolean = true,
 >
-  = (InferIfSchema<T>
-    & {
-      /**
-       * A unique key to use for the script, this can be used to load multiple of the same script with different options.
-       */
-      key?: string
-      scriptInput?: ScriptInput
-      scriptOptions?: Omit<NuxtUseScriptOptions, Bundelable extends true ? '' : 'bundle' | Usable extends true ? '' : 'use'>
-    })
-    | Partial<InferIfSchema<T>> & (
-    CanBypassOptions extends true ? {
-      /**
-       * A unique key to use for the script, this can be used to load multiple of the same script with different options.
-       */
-      key?: string
-      scriptInput: Required<Pick<ScriptInput, 'src'>> & ScriptInput
-      scriptOptions?: Omit<NuxtUseScriptOptions, Bundelable extends true ? '' : 'bundle' | Usable extends true ? '' : 'use'>
-    } : never)
+= Partial<InferIfSchema<T>>
+  & {
+    /**
+     * A unique key to use for the script, this can be used to load multiple of the same script with different options.
+     */
+    key?: string
+    scriptInput?: ScriptInput
+    scriptOptions?: Omit<NuxtUseScriptOptions, Bundelable extends true ? '' : 'bundle' | Usable extends true ? '' : 'use'>
+  }
 
 export interface RegistryScriptServerHandler {
   route: string
diff --git a/src/runtime/utils.ts b/src/runtime/utils.ts
index 62bbb9650..1c1c21e09 100644
--- a/src/runtime/utils.ts
+++ b/src/runtime/utils.ts
@@ -59,7 +59,7 @@ export function requireRegistryEndpoint(componentName: string, registryKey: stri
 
 export function useRegistryScript<T extends Record<string | symbol, any>, O = EmptyOptionsSchema>(registryKey: keyof ScriptRegistry | string, optionsFn: OptionsFn<O>, _userOptions?: RegistryScriptInput<O>): UseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>, T>> {
   const scriptConfig = scriptRuntimeConfig(registryKey as keyof ScriptRegistry)
-  const userOptions = Object.assign(_userOptions || {}, typeof scriptConfig === 'object' ? scriptConfig : {})
+  const userOptions = defu(_userOptions || {}, typeof scriptConfig === 'object' ? scriptConfig : {})
   const options = optionsFn(userOptions as InferIfSchema<O>, { scriptInput: userOptions.scriptInput as UseScriptInput & { src?: string } })
 
   // NEW: Handle NPM-only scripts differently

From be71b8c028527687c8cdad4e6939a080987bf715 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 18 Mar 2026 17:25:48 +1100
Subject: [PATCH 2/3] fix: resolve circular eslint indent rule conflict in
 RegistryScriptInput

---
 src/runtime/types.ts | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/runtime/types.ts b/src/runtime/types.ts
index 827d4a9d0..4259327bb 100644
--- a/src/runtime/types.ts
+++ b/src/runtime/types.ts
@@ -212,20 +212,20 @@ export type EmptyOptionsSchema = typeof _emptyOptions
 type ScriptInput = Script
 
 export type InferIfSchema<T> = T extends ObjectSchema<any, any> | UnionSchema<any, any> ? InferInput<T> : T
+export interface RegistryScriptInputExtras<Bundelable extends boolean = true, Usable extends boolean = false> {
+  /**
+   * A unique key to use for the script, this can be used to load multiple of the same script with different options.
+   */
+  key?: string
+  scriptInput?: ScriptInput
+  scriptOptions?: Omit<NuxtUseScriptOptions, Bundelable extends true ? '' : 'bundle' | Usable extends true ? '' : 'use'>
+}
+
 export type RegistryScriptInput<
   T = EmptyOptionsSchema,
   Bundelable extends boolean = true,
   Usable extends boolean = false,
->
-= Partial<InferIfSchema<T>>
-  & {
-    /**
-     * A unique key to use for the script, this can be used to load multiple of the same script with different options.
-     */
-    key?: string
-    scriptInput?: ScriptInput
-    scriptOptions?: Omit<NuxtUseScriptOptions, Bundelable extends true ? '' : 'bundle' | Usable extends true ? '' : 'use'>
-  }
+> = Partial<InferIfSchema<T>> & RegistryScriptInputExtras<Bundelable, Usable>
 
 export interface RegistryScriptServerHandler {
   route: string

From fa12a3f2e35b3a599e86e0b03327a12295ad8596 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Wed, 18 Mar 2026 17:39:45 +1100
Subject: [PATCH 3/3] fix: skip false registry entries in templatePlugin code
 generation

---
 src/templates.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/templates.ts b/src/templates.ts
index a1824b115..979a0f600 100644
--- a/src/templates.ts
+++ b/src/templates.ts
@@ -119,6 +119,8 @@ export function templatePlugin(config: Partial<ModuleOptions>, registry: Require
 
   // for global scripts, we can initialise them script away
   for (const [k, c] of Object.entries(config.registry || {})) {
+    if (c === false)
+      continue
     const importDefinition = registry.find(i => i.import.name.toLowerCase() === `usescript${k.toLowerCase()}`)
     if (importDefinition) {
       resolvedRegistryKeys.push(k)