docs: add overview for third parties (#25832)

Co-authored-by: Thorsten Kober <thorstenk@google.com>
Co-authored-by: Kara <kara@users.noreply.github.com>
Co-authored-by: Damian Głowala <damian.glowala.rebkow@gmail.com>
Co-authored-by: Houssein Djirdeh <houssein.djirdeh@gmail.com>
Co-authored-by: Julien Huang <julien.h.dev@gmail.com>
This commit is contained in:
Thorsten Kober 2024-02-22 06:30:49 -05:00 committed by GitHub
parent ffda918f54
commit 8ea1fa118b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -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 youre 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)
<sub>
source: Chrome User Experience Report,
date: October 2023,
devices: phone
</sub>
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
<script setup lang="ts">
useScript({
src: 'https://www.example.com/script.js'
})
</script>
```
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
<script setup lang="ts">
useScript({
src: 'https://www.example.com/script.js',
trigger: new Promise((resolve) => {
setTimeout(() => { resolve() }, 1000)
})
})
</script>
```
: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
<script setup lang="ts">
useStyles(['https://www.example.com/styles.css'])
</script>
```
You can use optional asset strategies to inline styles directly in the `head` section of your `document`.
```vue
<script setup lang="ts">
useStyles(
['https://www.example.com/styles.css'],
{ assetStrategy: 'inline' }
)
</script>
```
### 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 `<GoogleMaps>` and `<YoutubeEmbed>`
#### Google Analytics
The `useGoogleAnalytics` composable allows you to integrate Google Analytics in your Nuxt application.
```vue
<script setup lang="ts">
useGoogleAnalytics({
id: 'GA-123456789-1'
})
</script>
```
: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
<script setup lang="ts">
useGoogleTagManager({
id: 'GTM-ABCD12'
})
<script>
```
:read-more{to="/docs/api/composables/use-google-tag-manager"}
#### Google Maps
The `<GoogleMaps>` component initializes and displays a Google Map on your page using the Maps JavaScript API.
```vue
<template>
<div>
<GoogleMaps
api-key="API_KEY"
q="Space+Needle,Seattle+WA"
/>
</div>
</template>
```
:read-more{to="/docs/api/components/google-maps"}
#### YouTube Embed
The `<YoutubeEmbed>` component uses `lite-youtube-embed` under the hood to load and display a YouTube embed on your page faster.
```vue
<template>
<div>
<YoutubeEmbed
video-id="d_IFKP1Ofq0"
play-label="Play Video"
/>
</div>
</template>
```
:read-more{to="/docs/api/components/youtube-embed"}