From 74235272a480d4d8928327d5760e0ce277f05c53 Mon Sep 17 00:00:00 2001 From: Harlan Wilton Date: Fri, 5 Jul 2024 13:32:20 +1000 Subject: [PATCH] feat!: convert module config `globals` to object (#127) --- .../docs/1.guides/1.script-triggers.md | 6 +- docs/content/docs/1.guides/4.global.md | 120 +++++++++++------- src/module.ts | 11 +- src/templates.ts | 29 +++-- test/unit/templates.test.ts | 48 +++---- 5 files changed, 132 insertions(+), 82 deletions(-) diff --git a/docs/content/docs/1.guides/1.script-triggers.md b/docs/content/docs/1.guides/1.script-triggers.md index 85640f86..9e8ef56f 100644 --- a/docs/content/docs/1.guides/1.script-triggers.md +++ b/docs/content/docs/1.guides/1.script-triggers.md @@ -28,12 +28,12 @@ useScriptMetaPixel({ ```ts [Global Script] export default defineNuxtConfig({ scripts: { - globals: [ - ['https://example.com/script.js', { + globals: { + myScript: ['https://example.com/script.js', { // load however you like! trigger: 'onNuxtReady' }] - ] + } } }) ``` diff --git a/docs/content/docs/1.guides/4.global.md b/docs/content/docs/1.guides/4.global.md index 036bf94a..1e82d2c5 100644 --- a/docs/content/docs/1.guides/4.global.md +++ b/docs/content/docs/1.guides/4.global.md @@ -10,35 +10,95 @@ While the `app.head` method in Nuxt Config allows for loading global scripts, it ```ts export default defineNuxtConfig({ head: { - script: [ - { - src: 'https://analytics.com/tracker.js', - async: true, - defer: true, - } - ] + script: [ { src: 'https://analytics.com/tracker.js', async: true } ] } }) ``` A simpler method is now available: directly input the script URL into `scripts.globals`. You can also include optional settings to tailor the script loading process with specific optimizations in mind. -## How it Works +You may consider using global scripts when: +- The script isn't a supported [Registry Script](/docs/api/use-script#registry-script). +- You don't care about interacting with the API provided by the third-party script (e.g. you don't need to use `gtag` from Google Analytics). +- You are interacting with the API provided by the third-party script, but you don't care about type safety. + +Otherwise, it's recommended to use [useScript](/docs/api/use-script) to load scripts in a safer way. + +## Usage + +The `globals` key supports strings, objects and arrays. + +**Example: Load a script using just the src** + +```ts +export default defineNuxtConfig({ + scripts: { + globals: { + myScript: 'https://analytics.com/tracker.js', + } + } +}) +``` + +**Example: Load a script while providing extra script attributes** + +```ts +export default defineNuxtConfig({ + scripts: { + globals: { + myScript: { + src: 'https://example.com/script.js', + integrity: 'sha256-abc123', + } + } + } +}) +``` + + +You can optionally provide the script as an array which allows you to provide [Script Options](/docs/api/use-script#NuxtUseScriptOptions). + +```ts +export default defineNuxtConfig({ + scripts: { + globals: { + myScript: [ + { src: 'https://example.com/script.js' }, + // load the script as part of the hydration process instead of on idle + { trigger: 'client' } + ] + } + } +}) +``` -The `globals` configuration will be used to create a virtual Nuxt plugin that loads in the script using the `useScript` composable. This allows for the script to be loaded in with best practices in mind. +### Accessing a global script -This also means you can access your script anywhere in your Nuxt app without triggering the script to be loaded again. +All Nuxt Scripts are registered on the `$scripts` Nuxt App property. -For example, if we're loading in a tracking script we can use the `useScript` composable to access the underlying API. +For scripts registered through nuxt.config, type autocompletion is available. + +```vue + +``` + +## How it Works + +The `globals` configuration will be used to create a virtual Nuxt plugin that loads in the script using the `useScript` composable. + +As `useScript` is being used under the hood, it's important to understand the defaults and behavior of the [useScript](/api/use-script) composable.. ::code-group ```ts [nuxt.config.ts] export default defineNuxtConfig({ scripts: { - globals: [ - 'https://analytics.com/tracker.js', - ] + globals: { + tracker: 'https://analytics.com/tracker.js', + } } }) ``` @@ -46,7 +106,7 @@ export default defineNuxtConfig({ ```vue [components/Tracking.vue]