feat: support manual script deduping (#148)

Author: harlan-zw

docs/content/docs/1.guides/1.registry-scripts.md

@@ -97,16 +97,51 @@ of the script, so that it will never load.
 You can do this by providing a `mock` value to the registry script.
 
 ```ts [nuxt.config.ts]
-import { isDevelopment } from 'std-env'
+export default defineNuxtConfig({
+  $production: {
+    scripts: {
+      registry: {
+        googleAnalytics: {
+          id: 'YOUR_ID',
+        },
+      }
+    }
+  },
+})
+```
+
+### 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.
+
+```ts
+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:
+
+```ts
 export default defineNuxtConfig({
-  scripts: {
-    registry: {
-      googleAnalytics: isDevelopment
-        ? 'mock' // script won't load unless manually calling load()
-        : {
-            id: 'YOUR_ID',
-          },
+  runtimeConfig: {
+    public: {
+      scripts: {
+        gtag2: {
+          id: '', // NUXT_PUBLIC_SCRIPTS_GTAG2_ID
+        },
+      },
     },
   },
 })

playground/pages/third-parties/google-analytics/multiple.vue

@@ -0,0 +1,47 @@
+<script lang="ts" setup>
+import { useHead, useScriptGoogleAnalytics } from '#imports'
+
+useHead({
+  title: 'Google Analytics',
+})
+
+// composables return the underlying api as a proxy object and a $script with the script state
+const { gtag: gtag1, $script: $script1 } = useScriptGoogleAnalytics({
+  key: 'gtag1',
+  id: 'G-TR58L0EF8P',
+})
+
+const { gtag: gtag2, $script: $script2 } = useScriptGoogleAnalytics({
+  key: 'gtag2',
+  id: 'G-1234567890',
+})
+
+// id set via nuxt scripts module config
+gtag1('event', 'page_view', {
+  page_title: 'Google Analytics',
+  page_location: 'https://harlanzw.com/third-parties/google-analytics',
+  page_path: '/third-parties/google-analytics',
+})
+
+function triggerConversion() {
+  gtag2('event', 'conversion')
+}
+</script>
+
+<template>
+  <div>
+    <ClientOnly>
+      <div>
+        1 status: {{ $script1.status.value }}
+      </div>
+    </ClientOnly>
+    <ClientOnly>
+      <div>
+        2 status: {{ $script2.status.value }}
+      </div>
+    </ClientOnly>
+    <button @click="triggerConversion">
+      Trigger Conversion
+    </button>
+  </div>
+</template>

src/runtime/registry/clarity.ts

@@ -49,7 +49,7 @@ export function useScriptClarity<T extends ClarityApi>(
   _options?: ClarityInput,
 ) {
   return useRegistryScript<T, typeof ClarityOptions>(
-    'clarity',
+    _options?.key || 'clarity',
     options => ({
       scriptInput: {
         src: `https://www.clarity.ms/tag/${options.id}`,

src/runtime/registry/cloudflare-web-analytics.ts

@@ -38,7 +38,7 @@ export const CloudflareWebAnalyticsOptions = object({
 export type CloudflareWebAnalyticsInput = RegistryScriptInput<typeof CloudflareWebAnalyticsOptions>
 
 export function useScriptCloudflareWebAnalytics<T extends CloudflareWebAnalyticsApi>(_options?: CloudflareWebAnalyticsInput) {
-  return useRegistryScript<T, typeof CloudflareWebAnalyticsOptions>('cloudflareWebAnalytics', options => ({
+  return useRegistryScript<T, typeof CloudflareWebAnalyticsOptions>(_options?.key || 'cloudflareWebAnalytics', options => ({
     scriptInput: {
       'src': 'https://static.cloudflareinsights.com/beacon.min.js',
       'data-cf-beacon': JSON.stringify({ token: options.token, spa: options.spa || true }),

src/runtime/registry/crisp.ts

@@ -64,7 +64,7 @@ declare global {
 
 export function useScriptCrisp<T extends CrispApi>(_options?: CrispInput) {
   let readyPromise: Promise<void> = Promise.resolve()
-  return useRegistryScript<T, typeof CrispOptions>('crisp', options => ({
+  return useRegistryScript<T, typeof CrispOptions>(_options?.key || 'crisp', options => ({
     scriptInput: {
       src: 'https://client.crisp.chat/l.js', // can't be bundled
     },

src/runtime/registry/fathom-analytics.ts

@@ -47,7 +47,7 @@ declare global {
 }
 
 export function useScriptFathomAnalytics<T extends FathomAnalyticsApi>(_options?: FathomAnalyticsInput) {
-  return useRegistryScript<T, typeof FathomAnalyticsOptions>('fathomAnalytics', options => ({
+  return useRegistryScript<T, typeof FathomAnalyticsOptions>(_options?.key || 'fathomAnalytics', options => ({
     scriptInput: {
       src: 'https://cdn.usefathom.com/script.js', // can't be bundled
       // append the data attr's

src/runtime/registry/google-adsense.ts

@@ -31,7 +31,7 @@ declare global {
  */
 export function useScriptGoogleAdsense<T extends GoogleAdsenseApi>(_options?: GoogleAdsenseInput) {
   // Note: inputs.useScriptInput is not usable, needs to be normalized
-  return useRegistryScript<T, typeof GoogleAdsenseOptions>('googleAdsense', options => ({
+  return useRegistryScript<T, typeof GoogleAdsenseOptions>(_options?.key || 'googleAdsense', options => ({
     scriptInput: {
       src: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js',
     },

src/runtime/registry/google-maps.ts

@@ -38,7 +38,7 @@ declare global {
 
 export function useScriptGoogleMaps<T extends GoogleMapsApi>(_options?: GoogleMapsInput) {
   let readyPromise: Promise<void> = Promise.resolve()
-  return useRegistryScript<T, typeof GoogleMapsOptions>('googleMaps', (options) => {
+  return useRegistryScript<T, typeof GoogleMapsOptions>(_options?.key || 'googleMaps', (options) => {
     const libraries = options?.libraries || ['places']
     return {
       scriptInput: {

src/runtime/registry/hotjar.ts

@@ -22,7 +22,7 @@ export const HotjarOptions = object({
 export type HotjarInput = RegistryScriptInput<typeof HotjarOptions>
 
 export function useScriptHotjar<T extends HotjarApi>(_options?: HotjarInput) {
-  return useRegistryScript<T, typeof HotjarOptions>('hotjar', options => ({
+  return useRegistryScript<T, typeof HotjarOptions>(_options?.key || 'hotjar', options => ({
     scriptInput: {
       src: `https://static.hotjar.com/c/hotjar-${options?.id}.js?sv=${options?.sv || 6}`,
     },

src/runtime/registry/intercom.ts

@@ -50,7 +50,7 @@ declare global {
 }
 
 export function useScriptIntercom<T extends IntercomApi>(_options?: IntercomInput) {
-  return useRegistryScript<T, typeof IntercomOptions>('intercom', options => ({
+  return useRegistryScript<T, typeof IntercomOptions>(_options?.key || 'intercom', options => ({
     scriptInput: {
       src: joinURL(`https://widget.intercom.io/widget`, options?.app_id || ''),
     },