next
Version:
The React Framework
479 lines (356 loc) • 17 kB
Markdown
---
title: How to optimize third-party libraries
nav_title: Third Party Libraries
description: Optimize the performance of third-party libraries in your application with the `/third-parties` package.
---
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
**`/third-parties`** is a library that provides a collection of components and utilities that improve the performance and developer experience of loading popular third-party libraries in your Next.js application.
All third-party integrations provided by `/third-parties` have been optimized for performance and ease of use.
## Getting Started
To get started, install the `/third-parties` library:
```bash package="pnpm"
pnpm add /third-parties next
```
```bash package="npm"
npm install /third-parties next
```
```bash package="yarn"
yarn add /third-parties next
```
```bash package="bun"
bun add /third-parties next
```
{/* To do: Remove this paragraph once package becomes stable */}
`/third-parties` is currently an **experimental** library under active development. We recommend installing it with the **latest** or **canary** flags while we work on adding more third-party integrations.
## Google Third-Parties
All supported third-party libraries from Google can be imported from `/third-parties/google`.
### Google Tag Manager
The `GoogleTagManager` component can be used to instantiate a [Google Tag Manager](https://developers.google.com/tag-platform/tag-manager) container to your page. By default, it fetches the original inline script after hydration occurs on the page.
<AppOnly>
To load Google Tag Manager for all routes, include the component directly in your root layout and pass in your GTM container ID:
```tsx filename="app/layout.tsx" switcher
import { GoogleTagManager } from '/third-parties/google'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<GoogleTagManager gtmId="GTM-XYZ" />
<body>{children}</body>
</html>
)
}
```
```jsx filename="app/layout.js" switcher
import { GoogleTagManager } from '/third-parties/google'
export default function RootLayout({ children }) {
return (
<html lang="en">
<GoogleTagManager gtmId="GTM-XYZ" />
<body>{children}</body>
</html>
)
}
```
</AppOnly>
<PagesOnly>
To load Google Tag Manager for all routes, include the component directly in your custom `_app` and
pass in your GTM container ID:
```jsx filename="pages/_app.js"
import { GoogleTagManager } from '/third-parties/google'
export default function MyApp({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<GoogleTagManager gtmId="GTM-XYZ" />
</>
)
}
```
</PagesOnly>
To load Google Tag Manager for a single route, include the component in your page file:
<AppOnly>
```jsx filename="app/page.js"
import { GoogleTagManager } from '/third-parties/google'
export default function Page() {
return <GoogleTagManager gtmId="GTM-XYZ" />
}
```
</AppOnly>
<PagesOnly>
```jsx filename="pages/index.js"
import { GoogleTagManager } from '/third-parties/google'
export default function Page() {
return <GoogleTagManager gtmId="GTM-XYZ" />
}
```
</PagesOnly>
#### Sending Events
The `sendGTMEvent` function can be used to track user interactions on your page by sending events
using the `dataLayer` object. For this function to work, the `<GoogleTagManager />` component must be
included in either a parent layout, page, or component, or directly in the same file.
<AppOnly>
```jsx filename="app/page.js"
'use client'
import { sendGTMEvent } from '/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
>
Send Event
</button>
</div>
)
}
```
</AppOnly>
<PagesOnly>
```jsx filename="pages/index.js"
import { sendGTMEvent } from '/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
>
Send Event
</button>
</div>
)
}
```
</PagesOnly>
Refer to the Tag Manager [developer
documentation](https://developers.google.com/tag-platform/tag-manager/datalayer) to learn about the
different variables and events that can be passed into the function.
#### Server-side Tagging
If you're using a server-side tag manager and serving `gtm.js` scripts from your tagging server you can
use `gtmScriptUrl` option to specify the URL of the script.
#### Options
Options to pass to the Google Tag Manager. For a full list of options, read the [Google Tag Manager
docs](https://developers.google.com/tag-platform/tag-manager/datalayer).
| Name | Type | Description |
| --------------- | ---------- | ------------------------------------------------------------------------ |
| `gtmId` | Required\* | Your GTM container ID. Usually starts with `GTM-`. |
| `gtmScriptUrl` | Optional\* | GTM script URL. Defaults to `https://www.googletagmanager.com/gtm.js`. |
| `dataLayer` | Optional | Data layer object to instantiate the container with. |
| `dataLayerName` | Optional | Name of the data layer. Defaults to `dataLayer`. |
| `auth` | Optional | Value of authentication parameter (`gtm_auth`) for environment snippets. |
| `preview` | Optional | Value of preview parameter (`gtm_preview`) for environment snippets. |
\*`gtmId` can be omitted when `gtmScriptUrl` is provided to support [Google tag gateway for advertisers](https://developers.google.com/tag-platform/tag-manager/gateway/setup-guide?setup=manual).
### Google Analytics
The `GoogleAnalytics` component can be used to include [Google Analytics
4](https://developers.google.com/analytics/devguides/collection/ga4) to your page via the Google tag
(`gtag.js`). By default, it fetches the original scripts after hydration occurs on the page.
> **Recommendation**: 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`.
<AppOnly>
To load Google Analytics for all routes, include the component directly in your root layout and pass
in your measurement ID:
```tsx filename="app/layout.tsx" switcher
import { GoogleAnalytics } from '/third-parties/google'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
<GoogleAnalytics gaId="G-XYZ" />
</html>
)
}
```
```jsx filename="app/layout.js" switcher
import { GoogleAnalytics } from '/third-parties/google'
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
<GoogleAnalytics gaId="G-XYZ" />
</html>
)
}
```
</AppOnly>
<PagesOnly>
To load Google Analytics for all routes, include the component directly in your custom `_app` and
pass in your measurement ID:
```jsx filename="pages/_app.js"
import { GoogleAnalytics } from '/third-parties/google'
export default function MyApp({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<GoogleAnalytics gaId="G-XYZ" />
</>
)
}
```
</PagesOnly>
To load Google Analytics for a single route, include the component in your page file:
<AppOnly>
```jsx filename="app/page.js"
import { GoogleAnalytics } from '/third-parties/google'
export default function Page() {
return <GoogleAnalytics gaId="G-XYZ" />
}
```
</AppOnly>
<PagesOnly>
```jsx filename="pages/index.js"
import { GoogleAnalytics } from '/third-parties/google'
export default function Page() {
return <GoogleAnalytics gaId="G-XYZ" />
}
```
</PagesOnly>
#### Sending Events
The `sendGAEvent` function can be used to measure user interactions on your page by sending events
using the `dataLayer` object. For this function to work, the `<GoogleAnalytics />` component must be
included in either a parent layout, page, or component, or directly in the same file.
<AppOnly>
```jsx filename="app/page.js"
'use client'
import { sendGAEvent } from '/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
>
Send Event
</button>
</div>
)
}
```
</AppOnly>
<PagesOnly>
```jsx filename="pages/index.js"
import { sendGAEvent } from '/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
>
Send Event
</button>
</div>
)
}
```
</PagesOnly>
Refer to the Google Analytics [developer
documentation](https://developers.google.com/analytics/devguides/collection/ga4/event-parameters) to learn
more about event parameters.
#### Tracking Pageviews
Google Analytics automatically tracks pageviews when the browser history state changes. This means
that client-side navigations between Next.js routes will send pageview data without any configuration.
To ensure that client-side navigations are being measured correctly, verify that the [_“Enhanced
Measurement”_](https://support.google.com/analytics/answer/9216061#enable_disable) property is
enabled in your Admin panel and the _“Page changes based on browser history events”_ checkbox is
selected.
> **Note**: If you decide to manually send pageview events, make sure to disable the default
> pageview measurement to avoid having duplicate data. Refer to the Google Analytics [developer
> documentation](https://developers.google.com/analytics/devguides/collection/ga4/views?client_type=gtag#manual_pageviews)
> to learn more.
#### Options
Options to pass to the `<GoogleAnalytics>` component.
| Name | Type | Description |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `gaId` | Required | Your [measurement ID](https://support.google.com/analytics/answer/12270356). Usually starts with `G-`. |
| `dataLayerName` | Optional | Name of the data layer. Defaults to `dataLayer`. |
| `nonce` | Optional | A [nonce](/docs/app/guides/content-security-policy#nonces). |
### Google Maps Embed
The `GoogleMapsEmbed` component can be used to add a [Google Maps
Embed](https://developers.google.com/maps/documentation/embed/embedding-map) to your page. By
default, it uses the `loading` attribute to lazy-load the embed below the fold.
<AppOnly>
```jsx filename="app/page.js"
import { GoogleMapsEmbed } from '/third-parties/google'
export default function Page() {
return (
<GoogleMapsEmbed
apiKey="XYZ"
height={200}
width="100%"
mode="place"
q="Brooklyn+Bridge,New+York,NY"
/>
)
}
```
</AppOnly>
<PagesOnly>
```jsx filename="pages/index.js"
import { GoogleMapsEmbed } from '/third-parties/google'
export default function Page() {
return (
<GoogleMapsEmbed
apiKey="XYZ"
height={200}
width="100%"
mode="place"
q="Brooklyn+Bridge,New+York,NY"
/>
)
}
```
</PagesOnly>
#### Options
Options to pass to the Google Maps Embed. For a full list of options, read the [Google Map Embed
docs](https://developers.google.com/maps/documentation/embed/embedding-map).
| Name | Type | Description |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `apiKey` | Required | Your api key. |
| `mode` | Required | [Map mode](https://developers.google.com/maps/documentation/embed/embedding-map#choosing_map_modes) |
| `height` | Optional | Height of the embed. Defaults to `auto`. |
| `width` | Optional | Width of the embed. Defaults to `auto`. |
| `style` | Optional | Pass styles to the iframe. |
| `allowfullscreen` | Optional | Property to allow certain map parts to go full screen. |
| `loading` | Optional | Defaults to lazy. Consider changing if you know your embed will be above the fold. |
| `q` | Optional | Defines map marker location. _This may be required depending on the map mode_. |
| `center` | Optional | Defines the center of the map view. |
| `zoom` | Optional | Sets initial zoom level of the map. |
| `maptype` | Optional | Defines type of map tiles to load. |
| `language` | Optional | Defines the language to use for UI elements and for the display of labels on map tiles. |
| `region` | Optional | Defines the appropriate borders and labels to display, based on geo-political sensitivities. |
### YouTube Embed
The `YouTubeEmbed` component can be used to load and display a YouTube embed. This component loads
faster by using [`lite-youtube-embed`](https://github.com/paulirish/lite-youtube-embed) under the
hood.
<AppOnly>
```jsx filename="app/page.js"
import { YouTubeEmbed } from '/third-parties/google'
export default function Page() {
return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}
```
</AppOnly>
<PagesOnly>
```jsx filename="pages/index.js"
import { YouTubeEmbed } from '/third-parties/google'
export default function Page() {
return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}
```
</PagesOnly>
#### Options
| Name | Type | Description |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `videoid` | Required | YouTube video id. |
| `width` | Optional | Width of the video container. Defaults to `auto` |
| `height` | Optional | Height of the video container. Defaults to `auto` |
| `playlabel` | Optional | A visually hidden label for the play button for accessibility. |
| `params` | Optional | The video player params defined [here](https://developers.google.com/youtube/player_parameters#Parameters). <br/> Params are passed as a query param string. <br/> Eg: `params="controls=0&start=10&end=30"` |
| `style` | Optional | Used to apply styles to the video container. |