---
title: "Third Party Components"
description: "The @next/third-parties package provides a collection of performance-optimized components and utilities designed to seamlessly integrate popular third-party external libraries into Next.js applicat..."
last_updated: "2026-09-23T10:52:03.135025+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/ecosystem-packages/third-party-components"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/third-parties/src/ThirdPartyScriptEmbed.tsx](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/ThirdPartyScriptEmbed.tsx)
- [packages/next/src/pages/_document.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/pages/_document.tsx)
- [packages/next/src/client/script.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/script.tsx)
- [packages/third-parties/src/google/gtm.tsx](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/gtm.tsx)
- [packages/third-parties/src/google/youtube-embed.tsx](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/youtube-embed.tsx)
- [packages/third-parties/src/google/ga.tsx](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/ga.tsx)
- [packages/next/src/server/load-components.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/load-components.ts)
- [packages/third-parties/src/google/index.tsx](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/index.tsx)
- [packages/next/src/lib/metadata/metadata.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/lib/metadata/metadata.tsx)
- [packages/next/src/client/legacy/image.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/legacy/image.tsx)
- [packages/next/src/server/lib/patch-fetch.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/lib/patch-fetch.ts)
- [packages/next/src/client/next-turbopack.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/next-turbopack.ts)
- [packages/eslint-plugin-next/src/rules/next-script-for-ga.ts](https://github.com/blade47/next.js/blob/main/packages/eslint-plugin-next/src/rules/next-script-for-ga.ts)
- [packages/next/src/client/components/links.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/components/links.ts)
- [packages/third-parties/package.json](https://github.com/blade47/next.js/blob/main/packages/third-parties/package.json)
- [packages/third-parties/src/google/google-maps-embed.tsx](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/google-maps-embed.tsx)
- [packages/next/src/client/index.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/index.tsx)
- [packages/next/src/client/image-component.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/image-component.tsx)
- [packages/next/src/client/route-loader.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/route-loader.ts)
- [packages/next/src/server/route-modules/app-route/module.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/route-modules/app-route/module.ts)
- [packages/next/src/server/app-render/dynamic-rendering.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/dynamic-rendering.ts)
- [packages/next/script.js](https://github.com/blade47/next.js/blob/main/packages/next/script.js)
- [packages/next/src/server/app-render/create-component-tree.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/create-component-tree.tsx)
- [packages/next/src/client/app-index.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/client/app-index.tsx)
- [packages/next/src/server/app-render/rsc/preloads.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/server/app-render/rsc/preloads.ts)
- [packages/next/src/shared/lib/side-effect.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/side-effect.tsx)
- [packages/next/src/client/app-next-turbopack.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/app-next-turbopack.ts)
- [packages/next/src/shared/lib/loadable.shared-runtime.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/loadable.shared-runtime.tsx)
- [packages/next/src/shared/lib/dynamic.tsx](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/dynamic.tsx)
- [packages/next/src/client/next-dev-turbopack.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/next-dev-turbopack.ts)
</details>

## Overview

The `@next/third-parties` package provides a collection of performance-optimized components and utilities designed to seamlessly integrate popular third-party external libraries into Next.js applications. By leveraging framework-native script loading primitives, these components eliminate common performance bottlenecks associated with external embeds such as Google Tag Manager, Google Analytics, YouTube, and Google Maps.

Sources: [packages/third-parties/package.json:2-27](https://github.com/blade47/next.js/blob/main/packages/third-parties/package.json#L2-L27), [packages/third-parties/src/google/index.tsx:1-5](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/index.tsx#L1-L5)

At its core, the package relies on a shared wrapper architecture that handles script injection, container sizing, and telemetry signaling via performance marks to monitor feature usage safely in production. These abstractions align third-party service integration with Next.js execution strategies and static analysis rules, guiding developers toward optimized component patterns over raw HTML script tags.

Sources: [packages/third-parties/src/ThirdPartyScriptEmbed.tsx:1-50](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/ThirdPartyScriptEmbed.tsx#L1-L50), [packages/eslint-plugin-next/src/rules/next-script-for-ga.ts:10-83](https://github.com/blade47/next.js/blob/main/packages/eslint-plugin-next/src/rules/next-script-for-ga.ts#L10-L83)

## Package Architecture and Script Embed Foundation

### Package Architecture and Script Embed Foundation — Structure of @next/third-parties and the shared ThirdPartyScriptEmbed component

### Overview

The `@next/third-parties` package is structured around a modular export layout and a shared core component (`ThirdPartyScriptEmbed`) that underpins external service integrations. The package manifest defines its entry point exports under `exports`, exposing google-specific utilities through `./google` mapped to `./dist/google/index.js` and type definitions at `./dist/google/index.d.ts`. Peer dependencies enforce compatibility with `next` (`^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0-beta.0`) and `react` (`^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0`), while `third-party-capital` (`1.0.20`) acts as a primary dependency.

Sources: [packages/third-parties/package.json:1-38](https://github.com/blade47/next.js/blob/main/packages/third-parties/package.json#L1-L38), [packages/third-parties/src/google/index.tsx:1-5](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/index.tsx#L1-L5)

```typescript
export { default as GoogleMapsEmbed } from './google-maps-embed'
export { default as YouTubeEmbed } from './youtube-embed'
export { GoogleTagManager, sendGTMEvent } from './gtm'
export { GoogleAnalytics, sendGAEvent } from './ga'
```

Sources: [packages/third-parties/src/google/index.tsx:1-4](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/index.tsx#L1-L4)

### ScriptEmbed Types and Configuration Properties

The shared foundation utilizes the `ScriptEmbed` type definition to shape properties passed into client embeds. It supports optional fields for raw HTML string injection, explicit container dimensions, child elements, and telemetry data identifiers.

| Property | Type | Default | Purpose |
| :--- | :--- | :--- | :--- |
| `html` | `string \| null` | `undefined` | Raw HTML string to be injected via `dangerouslySetInnerHTML`. |
| `height` | `string \| number \| null` | `null` | Container height; appended with `px` if provided as a non-null value, otherwise defaults to `'auto'`. |
| `width` | `string \| number \| null` | `null` | Container width; appended with `px` if provided as a non-null value, otherwise defaults to `'auto'`. |
| `children` | `React.ReactElement \| React.ReactElement[]` | `undefined` | React element nodes rendered directly alongside the script container. |
| `dataNtpc` | `string` | `''` | Feature usage telemetry identifier appended to `data-ntpc` attributes and performance marks. |

Sources: [packages/third-parties/src/ThirdPartyScriptEmbed.tsx:5-19](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/ThirdPartyScriptEmbed.tsx#L5-L19)

### ThirdPartyScriptEmbed Execution Flow

The `ThirdPartyScriptEmbed` component executes a client-side lifecycle sequence upon mounting to render children, inject raw HTML containers, and emit low-overhead performance marks for feature usage telemetry.

```typescript
export default function ThirdPartyScriptEmbed({
  html,
  height = null,
  width = null,
  children,
  dataNtpc = '',
}: ScriptEmbed) {
  useEffect(() => {
    if (dataNtpc) {
      performance.mark('mark_feature_usage', {
        detail: {
          feature: `next-third-parties-${dataNtpc}`,
        },
      })
    }
  }, [dataNtpc])

  return (
    <>
      {children}
      {html ? (
        <div
          style={{
            height: height != null ? `${height}px` : 'auto',
            width: width != null ? `${width}px` : 'auto',
          }}
          data-ntpc={dataNtpc}
          dangerouslySetInnerHTML={{ __html: html }}
        />
      ) : null}
    </>
  )
}
```

Sources: [packages/third-parties/src/ThirdPartyScriptEmbed.tsx:13-50](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/ThirdPartyScriptEmbed.tsx#L13-L50)

> [!NOTE]
> `performance.mark` is employed specifically as a lightweight feature-usage signal rather than for timing benchmarks. Because it has minimal overhead, it runs safely in production environments as a widely available browser API to track active `@next/third-parties` integrations.

Sources: [packages/third-parties/src/ThirdPartyScriptEmbed.tsx:21-29](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/ThirdPartyScriptEmbed.tsx#L21-L29)

## Google Tag Manager and Analytics Integration

### Overview

The `GoogleTagManager` and `GoogleAnalytics` components serve as client-side React wrappers (`'use client'`) that inject script tags using Next.js's underlying `Script` component. They track feature usage via `performance.mark` and manage data layers for event dispatching.

Sources: [packages/third-parties/src/google/gtm.tsx:1-51](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/gtm.tsx#L1-L51), [packages/third-parties/src/google/ga.tsx:1-34](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/ga.tsx#L1-L34)

### Google Tag Manager Integration and Parameters

The `GoogleTagManager` component builds a script URL from `gtmScriptUrl` (defaulting to `https://www.googletagmanager.com/gtm.js`) and attaches query parameters based on props. It also tracks usage by invoking `performance.mark('mark_feature_usage', { detail: { feature: 'next-third-parties-gtm' } })`.

| Property | Type | Default | Purpose |
| :--- | :--- | :--- | :--- |
| `gtmId` | `string` | `undefined` | Google Tag Manager container ID (`id` search parameter). |
| `gtmScriptUrl` | `string` | `'https://www.googletagmanager.com/gtm.js'` | Base URL for the GTM script. |
| `dataLayerName` | `string` | `'dataLayer'` | Custom data layer variable name. |
| `auth` | `string` | `undefined` | Environment authentication token (`gtm_auth` search parameter). |
| `preview` | `string` | `undefined` | Environment preview token (`gtm_preview` search parameter and `gtm_cookies_win=x`). |
| `dataLayer` | `Object` | `undefined` | Initial data layer object pushed during initialization. |
| `nonce` | `string` | `undefined` | Content Security Policy nonce for injected scripts. |

Sources: [packages/third-parties/src/google/gtm.tsx:10-51](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/gtm.tsx#L10-L51)

> [!NOTE]
> `sendGTMEvent` evaluates the active data layer name—falling back to `currDataLayerName` if omitted—ensuring that events can be successfully queued before GTM has finished initializing.

Sources: [packages/third-parties/src/google/gtm.tsx:77-83](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/gtm.tsx#L77-L83)

### Google Analytics Integration and Event Dispatch

The `GoogleAnalytics` component accepts `gaId`, `debugMode`, `dataLayerName`, and `nonce`. It initializes the global data layer queue, defines the `gtag` helper function, and loads the external `gtag/js` script.

| Property | Type | Default | Purpose |
| :--- | :--- | :--- | :--- |
| `gaId` | `string` | `undefined` | Measurement ID for Google Analytics. |
| `debugMode` | `boolean` | `undefined` | Enables debug mode (`{ 'debug_mode': true }`) in the `gtag config` command. |
| `dataLayerName` | `string` | `'dataLayer'` | Custom data layer array name on the window object. |
| `nonce` | `string` | `undefined` | Content Security Policy nonce for initialization scripts. |

Sources: [packages/third-parties/src/google/ga.tsx:16-57](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/ga.tsx#L16-L57)

> [!WARNING]
> Calling `sendGAEvent` before `GoogleAnalytics` has mounted and initialized logs a warning to the console and exits early without pushing arguments to the data layer.

Sources: [packages/third-parties/src/google/ga.tsx:59-72](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/ga.tsx#L59-L72)

## Optimized YouTube and Maps Embeds

### Optimized YouTube and Maps Embeds

### Overview

The `YouTubeEmbed` and `GoogleMapsEmbed` components leverage external standards from `third-party-capital` wrapped by the shared `ThirdPartyScriptEmbed` layer. They handle dynamic script generation, stylesheet propagation, and dimension sizing.

Sources: [packages/third-parties/src/google/youtube-embed.tsx:4-34](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/youtube-embed.tsx#L4-L34), [packages/third-parties/src/google/google-maps-embed.tsx:1-17](https://github.com/blade47/src/next.js/blob/main/packages/third-parties/src/google/google-maps-embed.tsx#L1-L17)

### Script Strategy Mappings

`YouTubeEmbed` maps strategy identifiers returned by `third-party-capital` to Next.js `Script` component loading strategies.

| Strategy Key | Next.js Script Strategy | Meaning / Behavior |
| :--- | :--- | :--- |
| `server` | `beforeInteractive` | Load before the page is interactive. |
| `client` | `afterInteractive` | Load immediately after page interactivity. |
| `idle` | `lazyOnload` | Load during browser idle time. |
| `worker` | `worker` | Load in a web worker (if supported). |

Sources: [packages/third-parties/src/google/youtube-embed.tsx:9-32](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/youtube-embed.tsx#L9-L32)

> [!NOTE]
> `GoogleMapsEmbed` restructures component props by extracting `apiKey` and passing it under the `key` property expected by `TPCGoogleMapEmbed`.

Sources: [packages/third-parties/src/google/google-maps-embed.tsx:6-9](https://github.com/blade47/next.js/blob/main/packages/third-parties/src/google/google-maps-embed.tsx#L6-L9)

## Core Script Loader Execution Strategies

### Overview

The `next/script` component manages third-party script loading lifecycles through document traversal, client-side caching, and strategy mapping. During server-side rendering, `handleDocumentScriptLoaderItems` traverses `Head` and `<body>` elements to identify script loader items, assigning `__NEXT_DATA__.scriptLoader` with parsed configurations.

Sources: [packages/next/src/pages/_document.tsx:744-799](https://github.com/blade47/next.js/blob/main/packages/next/src/pages/_document.tsx#L744-L799)

### Script Loading Lifecycle and Strategies

The `Script` component delegates loading behavior based on the `strategy` prop. When mounted, `useEffect` hooks manage execution timing, verifying against `LoadCache` to prevent redundant initializations across remounts.

| Strategy | Execution Timing | Behavior in App/Pages Directory |
| :--- | :--- | :--- |
| `beforeInteractive` | Prior to page hydration | Injected via `self.__next_s` queue or preloaded using `ReactDOM.preload`. |
| `afterInteractive` | Immediately after page load | Default strategy; executed via `loadScript`. |
| `lazyOnload` | During browser idle time | Executed via `loadLazyScript`. |
| `worker` | Offloaded to a web worker | Queued in `scripts.worker` via HeadManager context. |

Sources: [packages/next/src/client/script.tsx:200-296](https://github.com/blade47/next.js/blob/main/packages/next/src/client/script.tsx#L200-L296)

> [!WARNING]
> For `beforeInteractive` scripts lacking a `src` attribute, inline content inside `dangerouslySetInnerHTML` is extracted and reassigned to `restProps.children` before serialization.

Sources: [packages/next/src/client/script.tsx:318-326](https://github.com/blade47/next.js/blob/main/packages/next/src/client/script.tsx#L318-L326)

### Side-Effect Head Management

The `SideEffect` component coordinates head element updates by collecting mounted instances, reducing them via `reduceComponentsToState`, and flushing pending updates through layout and effect passes.

Sources: [packages/next/src/shared/lib/side-effect.tsx:17-73](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/side-effect.tsx#L17-L73)

> [!TIP]
> When multiple `SideEffect` components render simultaneously, updates are consolidated by storing the last unflushed `emitChange` reference in the `_pendingUpdate` singleton during the layout effect pass.

Sources: [packages/next/src/shared/lib/side-effect.tsx:43-57](https://github.com/blade47/next.js/blob/main/packages/next/src/shared/lib/side-effect.tsx#L43-L57)

## Static Analysis and Analytics Lint Rules

### Overview

To enforce best practices regarding framework-optimized script loading, Next.js provides static analysis through ESLint rules. Specifically, `eslint-plugin-next` includes the rule `next-script-for-ga`, which detects raw `<script>` tags loading analytics or tag manager libraries and prompts developers to adopt components from `@next/third-parties/google`.

Sources: [packages/eslint-plugin-next/src/rules/next-script-for-ga.ts:1-25](https://github.com/blade47/next.js/blob/main/packages/eslint-plugin-next/src/rules/next-script-for-ga.ts#L1-L25)

### Rule Architecture and Target URLs

The `next-script-for-ga` rule inspects JSX opening elements, identifying `script` tags by checking `node.name.name`. It validates both `src` attributes and `dangerouslySetInnerHTML` children against official Google Analytics and Google Tag Manager endpoints.

| Rule Constant / Identifier | Target URL / Substring | Error Message Output |
| :--- | :--- | :--- |
| `GOOGLE_ANALYTICS_URL` / `GOOGLE_ANALYTICS_SRC` | `www.google-analytics.com/analytics.js` | `Prefer \`GoogleAnalytics\` component from \`@next/third-parties/google\` when using the inline script for Google Analytics.` |
| `GOOGLE_TAG_MANAGER_URL` / `GOOGLE_TAG_MANAGER_SRC` | `www.googletagmanager.com/gtag/js`, `www.googletagmanager.com/gtm.js` | `Prefer \`GoogleTagManager\` component from \`@next/third-parties/google\` when using the inline script for Google Tag Manager.` |

Sources: [packages/eslint-plugin-next/src/rules/next-script-for-ga.ts:4-14](https://github.com/blade47/next.js/blob/main/packages/eslint-plugin-next/src/rules/next-script-for-ga.ts#L4-L14)

> [!WARNING]
> The rule evaluates raw HTML content inside `dangerouslySetInnerHTML` by extracting AST quasis and verifying whether the raw string includes analytics endpoint signatures.

Sources: [packages/eslint-plugin-next/src/rules/next-script-for-ga.ts:56-78](https://github.com/blade47/next.js/blob/main/packages/eslint-plugin-next/src/rules/next-script-for-ga.ts#L56-L78)

## Related

- [App Server Rendering](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/app-router-rendering/app-server-rendering)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.