Merge 1376da6a78 into cf8142b734

docs/1.getting-started/5.third-parties.md

@@ -0,0 +1,132 @@
+---
+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 "}
+
+### 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"}

docs/3.api/1.components/12.google-maps.md

@@ -0,0 +1,64 @@
+---
+title: "<GoogleMaps>"
+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 `<GoogleMaps>` 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
+<template>
+  <div>
+    <GoogleMaps
+      api-key="API_KEY"
+      width="600"
+      height="400"
+      q="Space+Needle,Seattle+WA"
+    />
+  </div>
+</template>
+```
+
+## Example with Coordinates
+
+```vue
+<template>
+  <div>
+    <GoogleMaps
+      api-key="API_KEY"
+      width="600"
+      height="400"
+      :center="{ lat: 47.62065090386302, lng: -122.34932031714334 }"
+    />
+  </div>
+</template>
+```
+
+## 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.

docs/3.api/1.components/13.youtube-embed.md

@@ -0,0 +1,39 @@
+---
+title: "<YoutubeEmbed>"
+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 `<YoutubeEmbed>` 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
+<template>
+  <div>
+    <YoutubeEmbed
+      video-id="d_IFKP1Ofq0"
+      play-label="Play"
+    />
+  </div>
+</template>
+```
+
+## 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.

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.
+::
+
+## Minimal Example
+
+```vue
+<script setup>
+useGoogleAnalytics({ id: 'GA-123456789-1' })
+</script>
+```
+
+## Example with custom event
+
+```vue
+<script setup>
+const { $script } = useGoogleAnalytics({
+  id: 'GA-123456789-1',
+})
+
+$script.waitForLoad().then(({ gtag }) => {
+  gtag('event', 'some_custom_event', { time: new Date() })
+})
+</script>
+```
+
+## Type
+
+```ts
+useGoogleAnalytics(options: ThirdPartyScriptOptions<GoogleAnalyticsOptions, GoogleAnalyticsApi>): ThirdPartyScriptApi<GoogleAnalyticsApi>
+```
+
+## 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).
+::

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
+<script setup>
+useGoogleTagManager({ id: 'GTM-123456' })
+</script>
+```
+
+## Example with Custom Event
+
+```vue
+<script setup>
+const { $script } = useGoogleTagManager({
+  id: 'GTM-123456'
+})
+
+$script.waitForLoad().then(({ dataLayer }) => {
+  dataLayer.push({
+    event: 'pageview',
+    page_path: '/google-tag-manager'
+  })
+})
+</script>
+```
+
+## Type
+
+```ts
+useGoogleTagManager(options: ThirdPartyScriptOptions<GoogleTagManagerOptions, GoogleTagManagerApi>): ThirdPartyScriptApi<GoogleTagManagerApi>
+```
+
+## 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).
+::