mirror of
https://github.com/nuxt/nuxt.git
synced 2024-11-22 05:35:13 +00:00
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:
parent
ffda918f54
commit
8ea1fa118b
153
docs/1.getting-started/5.third-parties.md
Normal file
153
docs/1.getting-started/5.third-parties.md
Normal 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 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)
|
||||
<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"}
|
Loading…
Reference in New Issue
Block a user