From 73b8f07fec55c7d19966bb90eaeab1280240b2c5 Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Tue, 23 Jan 2024 15:52:59 +0000 Subject: [PATCH 1/5] chore: diverge From d0caae3c108a3a88001ef81b27c34948552664e5 Mon Sep 17 00:00:00 2001 From: Thorsten Kober Date: Thu, 1 Feb 2024 19:33:36 -0500 Subject: [PATCH 2/5] docs: add `useGoogleAnalytics` to api documentation (#25403) --- .../2.composables/use-google-analytics.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/3.api/2.composables/use-google-analytics.md diff --git a/docs/3.api/2.composables/use-google-analytics.md b/docs/3.api/2.composables/use-google-analytics.md new file mode 100644 index 0000000000..0a83e2587b --- /dev/null +++ b/docs/3.api/2.composables/use-google-analytics.md @@ -0,0 +1,61 @@ +--- +title: useGoogleAnalytics +description: useGoogleAnalytics allows you to load and initialize Google Analytics in your Nuxt app. +links: + - label: Source + icon: i-simple-icons-github + to: https://github.com/nuxt/scripts-and-assets/blob/main/modules/nuxt-third-party-capital/src/runtime/composables/googleAnalytics.ts + size: xs +--- + +The `useGoogleAnalytics` composable function allows you to include [Google Analytics 4](https://developers.google.com/analytics/devguides/collection/ga4) in your Nuxt application. + +::callout +If Google Tag Manager is already included in your application, you can configure Google Analytics directly using it, rather than including Google Analytics as a separate component. Refer to the [documentation](https://developers.google.com/analytics/devguides/collection/ga4/tag-options#what-is-gtm) to learn more about the differences between Tag Manager and gtag.js. +:: + +## Type + +```ts +useGoogleAnalytics(options: ThirdPartyScriptOptions): ThirdPartyScriptApi +``` + +## Params + +An object containing the following options: + +| name | type | description | +|:-----|:-------|:--------------------------------| +| id | string | Google Analytics [measurement ID](https://support.google.com/analytics/answer/12270356). (required) | + +## Return values + +An object that contains a special `$script` property that gives you access to the underlying script instance. + +- `$script.waitForLoad`: A promise that resolves when the script is ready to use. It exposes `gtag` and `dataLayer`, which lets you interact with the API. + +::callout +Learn more about [useScript](https://unhead.unjs.io/usage/composables/use-script). +:: + +## Minimal example + +```vue + +``` + +## Example with custom event + +```vue + +``` From ffda918f54d0c9a38316d77812d19a791bc6b59c Mon Sep 17 00:00:00 2001 From: Thorsten Kober Date: Sat, 3 Feb 2024 18:04:46 -0500 Subject: [PATCH 3/5] docs: add remaining third-party-capital api docs (#25592) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Houssein Djirdeh Co-authored-by: Julien Huang Co-authored-by: Damian Głowala --- docs/3.api/1.components/12.google-maps.md | 64 +++++++++++++++++++ docs/3.api/1.components/13.youtube-embed.md | 39 +++++++++++ .../2.composables/use-google-analytics.md | 50 +++++++-------- .../2.composables/use-google-tag-manager.md | 60 +++++++++++++++++ 4 files changed, 188 insertions(+), 25 deletions(-) create mode 100644 docs/3.api/1.components/12.google-maps.md create mode 100644 docs/3.api/1.components/13.youtube-embed.md create mode 100644 docs/3.api/2.composables/use-google-tag-manager.md diff --git a/docs/3.api/1.components/12.google-maps.md b/docs/3.api/1.components/12.google-maps.md new file mode 100644 index 0000000000..715c27ec1b --- /dev/null +++ b/docs/3.api/1.components/12.google-maps.md @@ -0,0 +1,64 @@ +--- +title: "" +description: A simple and performant Google Maps component. +links: + - label: Source + icon: i-simple-icons-github + to: https://github.com/nuxt/scripts-and-assets/blob/main/modules/nuxt-third-party-capital/src/runtime/components/GoogleMaps.ts + size: xs +--- + +The `` component uses the [Maps JavaScript API](https://developers.google.com/maps/documentation/javascript) to load a map to your page. + +::callout +You need an API key to use Google Maps. +:: + +## Example with Query + +```vue + +``` + +## Example with Coordinates + +```vue + +``` + +## Props + +- `apiKey`: The [API key](https://developers.google.com/maps/documentation/javascript/get-api-key) to use Google Maps API. + - **type**: `string` + - **required** +- `q`: A query to search for. + - **type**: `string` +- `center`: Coordinates to set the map to + - **type**: `LatLng` +- `zoom`: Zoom value for the map + - **type**: `number` +- `width`: Width of the player + - **type**: `string` +- `height`: Height of the player + - **type**: `string` +- `params`: [Parameters](https://developers.google.com/maps/documentation/javascript/load-maps-js-api#optional_parameters) for the map. + +Either a query (q) or coordinates (center) are needed for the map to function properly. diff --git a/docs/3.api/1.components/13.youtube-embed.md b/docs/3.api/1.components/13.youtube-embed.md new file mode 100644 index 0000000000..97aa16597f --- /dev/null +++ b/docs/3.api/1.components/13.youtube-embed.md @@ -0,0 +1,39 @@ +--- +title: "" +description: A simple and performant YouTube component. +links: + - label: Source + icon: i-simple-icons-github + to: https://github.com/nuxt/scripts-and-assets/blob/main/modules/nuxt-third-party-capital/src/runtime/components/YoutubeEmbed.ts + size: xs +--- + +The `` component can be used to display a YouTube embed. +It uses [lite-youtube-embed](https://github.com/paulirish/lite-youtube-embed) to load significantly faster. + +## Minimal Example + +```vue + +``` + +## Props + +- `videoId`: The ID of the video + - **type**: `string` + - **required** +- `playLabel`: The label of the play button. This is for a11y purposes. + - **type**: `string` + - **required** +- `width`: Width of the player + - **type**: `string` +- `height`: Height of the player + - **type**: `string` +- `params`: [Parameters](https://developers.google.com/youtube/player_parameters#Parameters) for the player. diff --git a/docs/3.api/2.composables/use-google-analytics.md b/docs/3.api/2.composables/use-google-analytics.md index 0a83e2587b..2c52736397 100644 --- a/docs/3.api/2.composables/use-google-analytics.md +++ b/docs/3.api/2.composables/use-google-analytics.md @@ -14,31 +14,7 @@ The `useGoogleAnalytics` composable function allows you to include [Google Analy If Google Tag Manager is already included in your application, you can configure Google Analytics directly using it, rather than including Google Analytics as a separate component. Refer to the [documentation](https://developers.google.com/analytics/devguides/collection/ga4/tag-options#what-is-gtm) to learn more about the differences between Tag Manager and gtag.js. :: -## Type - -```ts -useGoogleAnalytics(options: ThirdPartyScriptOptions): ThirdPartyScriptApi -``` - -## Params - -An object containing the following options: - -| name | type | description | -|:-----|:-------|:--------------------------------| -| id | string | Google Analytics [measurement ID](https://support.google.com/analytics/answer/12270356). (required) | - -## Return values - -An object that contains a special `$script` property that gives you access to the underlying script instance. - -- `$script.waitForLoad`: A promise that resolves when the script is ready to use. It exposes `gtag` and `dataLayer`, which lets you interact with the API. - -::callout -Learn more about [useScript](https://unhead.unjs.io/usage/composables/use-script). -:: - -## Minimal example +## Minimal Example ```vue ``` + +## Type + +```ts +useGoogleAnalytics(options: ThirdPartyScriptOptions): ThirdPartyScriptApi +``` + +## Params + +An object containing the following options: + +- `id`: Google Analytics [measurement ID](https://support.google.com/analytics/answer/12270356). + - **type**: `string` + - **required** + +## Return Values + +An object that contains a special `$script` property that gives you access to the underlying script instance. + +- `$script.waitForLoad`: A promise that resolves when the script is ready to use. It exposes `gtag` and `dataLayer`, which lets you interact with the API. + +::callout +Learn more about [`useScript`](https://unhead.unjs.io/usage/composables/use-script). +:: diff --git a/docs/3.api/2.composables/use-google-tag-manager.md b/docs/3.api/2.composables/use-google-tag-manager.md new file mode 100644 index 0000000000..55141258cf --- /dev/null +++ b/docs/3.api/2.composables/use-google-tag-manager.md @@ -0,0 +1,60 @@ +--- +title: useGoogleTagManager +description: useGoogleTagManager allows you to install Google Tag Manager in your Nuxt app. +links: + - label: Source + icon: i-simple-icons-github + to: https://github.com/nuxt/scripts-and-assets/blob/main/modules/nuxt-third-party-capital/src/runtime/composables/googleTagManager.ts + size: xs +--- + +The `useGoogleTagManager` composable allows you to install [Google Tag Manager](https://developers.google.com/tag-platform/tag-manager/web) in your Nuxt application. + +## Minimal Example + +```vue + +``` + +## Example with Custom Event + +```vue + +``` + +## Type + +```ts +useGoogleTagManager(options: ThirdPartyScriptOptions): ThirdPartyScriptApi +``` + +## Params + +An object containing the following options: + +- `id`: Your GTM container ID. Usually starts with 'GTM-'. + - **type**: `string` + - **required** + +## Return Values + +An object that contains a special `$script` property that gives you access to the underlying script instance. + +- `$script.waitForLoad`: A promise that resolves when the script is ready to use. It exposes `google_tag_manager` and `dataLayer`, which lets you interact with the API. + +::callout +Learn more about [`useScript`](https://unhead.unjs.io/usage/composables/use-script). +:: From 8ea1fa118b71de6e94f5ec2d31788fd426a44df3 Mon Sep 17 00:00:00 2001 From: Thorsten Kober Date: Thu, 22 Feb 2024 06:30:49 -0500 Subject: [PATCH 4/5] docs: add overview for third parties (#25832) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Kober Co-authored-by: Kara Co-authored-by: Damian Głowala Co-authored-by: Houssein Djirdeh Co-authored-by: Julien Huang --- docs/1.getting-started/5.third-parties.md | 153 ++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 docs/1.getting-started/5.third-parties.md diff --git a/docs/1.getting-started/5.third-parties.md b/docs/1.getting-started/5.third-parties.md new file mode 100644 index 0000000000..130742474a --- /dev/null +++ b/docs/1.getting-started/5.third-parties.md @@ -0,0 +1,153 @@ +--- +title: Third Parties +description: Learn how to optimize the performance of third-party resources using built-in composables and components. +navigation.icon: i-ph-users-duotone +--- + +Nuxt provides a number of composables and built-in libraries that make it easier -- and faster -- to load third-party resources in your application. + +- `useScript`: Load any third-party script with server-side rendering support and a proxied API. +- `useStyles`: Load any third-party stylesheet using various asset strategies. +- Third-Party Wrappers: Wrapper components and composables that make it easier to include different popular third parties efficiently. + +## How Third Parties Can Impact User Experience + +Third parties are external resources included, but not directly controlled, by a site owner to add new functionality to a website. Popular examples of third parties include analytics, video embeds, maps, and social media integrations. Typically, third-party providers offer code snippets that can be added to the `head` or `body` section of the document. + +Adding a single third-party resource to your Nuxt application might not have any noticeable impact on performance, but it can quickly begin to affect user experience if you’re not careful. Many third parties, especially scripts, can take a relatively long time to download and execute, which can delay user interactivity and block page rendering. + +Data from the Chrome User Experience Report shows that Nuxt sites that load more third-party resources have lower [Interaction to Next Paint](https://web.dev/articles/inp) (INP) and [Largest Contentful Paint](https://web.dev/articles/lcp) (LCP) pass rates. + +![Chrome User Experience Report chart](/assets/docs/getting-started/third-parties/chart.png) + +source: Chrome User Experience Report, +date: October 2023, +devices: phone + + +While the chart's correlation does not automatically indicate causation, lab experiments and data from the [Web Almanac](https://almanac.httparchive.org/en/2022/third-parties) provide further evidence that third-party resources significantly affect page performance. + +## Optimizing Third Party Performance + +In general, it can be difficult to determine the most optimal way to load different third-party resources. Nuxt provides a number of utilities to improve both the developer and user experience of loading third parties. + +::callout +If you're using very popular third-party libraries, please check the [Third-Party Wrappers](#third-party-wrappers) section for available pre-configured solutions. +:: + +### useScript + +The `useScript` composable enables you to load third-party scripts with SSR support and a proxied API. It works out of the box, requiring just a URL that points to the script resource. + +```vue + +``` + +Optional triggers and asset strategies can be used to allow for more fine-grained control over how, and when, the script should be loaded. In the following example, the script will load once the promise provided in the trigger resolves (1 second later). + +```vue + +``` + +:read-more{to="https://unhead.unjs.io/usage/composables/use-script "} + +### useStyles + +The `useStyles` composable enables you to leverage `nuxt-assets` for third-party stylesheets. + +```vue + +``` + +You can use optional asset strategies to inline styles directly in the `head` section of your `document`. + +```vue + +``` + +### Third-Party Wrappers + +Nuxt provides a collection of utilities that are already configured to load and initialize popular third parties in the most performant way. These include: + +- Composables to fetch scripts such as `useGoogleAnalytics` and `useGoogleTagManager` +- Components to load embeds such as `` and `` + +#### Google Analytics + +The `useGoogleAnalytics` composable allows you to integrate Google Analytics in your Nuxt application. + +```vue + +``` + +:read-more{to="/docs/api/composables/use-google-analytics"} + +#### Google Tag Manager + +The `useGoogleTagManager` composable makes it easier to include Google Tag Manager in your Nuxt application. + +```vue + -``` - -You can use optional asset strategies to inline styles directly in the `head` section of your `document`. - -```vue - -``` - ### Third-Party Wrappers Nuxt provides a collection of utilities that are already configured to load and initialize popular third parties in the most performant way. These include: