Unverified Commit 8d6f8324 authored by Guilherme Sehn's avatar Guilherme Sehn Committed by GitHub

Re-add Partytown custom configuration to `Script` component documentation (#68946)

### What?

Add documentation about Partytown configuration on the `Script`
documentation page.

### Why?

The
[`Script`](https://nextjs.org/docs/pages/building-your-application/optimizing/scripts)
component with the `strategy` prop set to `worker` uses
[Partytown](https://partytown.builder.io/) under the hood.

Users may need to customize [Partytown
options](https://partytown.builder.io/configuration) such as `forward`,
`loadScriptsOnMainThread`, and `resolveUrl`, to allow for third party
scripts such as Segment and Google Tag Manager to work properly.

This used to be documented on `docs/basic-features/script.md`, as you
can see on the [pull request that originally introduced the `worker`
strategy](https://github.com/vercel/next.js/pull/34244/files#diff-62dbdb4bc703f7997ea259ad68d8e823d9fafed1e9571155e01c4de21abb6b47R165-R197),
but this doc page was removed (potentially unintendedly) on
https://github.com/vercel/next.js/pull/50701, and there's no longer
mention of Partytown configuration in Next.js docs.

### How?

Adding back the documentation text originally written by
@housseindjirdeh in his pull request
https://github.com/vercel/next.js/pull/34244

Fixes https://github.com/vercel/next.js/issues/68943

---------
Co-authored-by: 's avatarsamcx <sam@vercel.com>
parent df82c460
...@@ -175,6 +175,53 @@ export default function Home() { ...@@ -175,6 +175,53 @@ export default function Home() {
There are a number of trade-offs that need to be considered when loading a third-party script in a web worker. Please see Partytown's [tradeoffs](https://partytown.builder.io/trade-offs) documentation for more information. There are a number of trade-offs that need to be considered when loading a third-party script in a web worker. Please see Partytown's [tradeoffs](https://partytown.builder.io/trade-offs) documentation for more information.
<PagesOnly>
#### Using custom Partytown configuration
Although the `worker` strategy does not require any additional configuration to work, Partytown supports the use of a config object to modify some of its settings, including enabling `debug` mode and forwarding events and triggers.
If you would like to add additonal configuration options, you can include it within the `<Head />` component used in a [custom `_document.js`](/docs/pages/building-your-application/routing/custom-document):
```jsx filename="_pages/document.jsx"
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html>
<Head>
<script
data-partytown-config
dangerouslySetInnerHTML={{
__html: `
partytown = {
lib: "/_next/static/~partytown/",
debug: true
};
`,
}}
/>
</Head>
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
```
In order to modify Partytown's configuration, the following conditions must be met:
1. The `data-partytown-config` attribute must be used in order to overwrite the default configuration used by Next.js
2. Unless you decide to save Partytown's library files in a separate directory, the `lib: "/_next/static/~partytown/"` property and value must be included in the configuration object in order to let Partytown know where Next.js stores the necessary static files.
> **Note**: If you are using an [asset prefix](/docs/pages/api-reference/next-config-js/assetPrefix) and would like to modify Partytown's default configuration, you must include it as part of the `lib` path.
Take a look at Partytown's [configuration options](https://partytown.builder.io/configuration) to see the full list of other properties that can be added.
</PagesOnly>
### Inline Scripts ### Inline Scripts
Inline scripts, or scripts not loaded from an external file, are also supported by the Script component. They can be written by placing the JavaScript within curly braces: Inline scripts, or scripts not loaded from an external file, are also supported by the Script component. They can be written by placing the JavaScript within curly braces:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment