Skip to content

Commit 1352998

Browse files
hiro08ghhiro08gh
authored
Merge pull request #311 from Nextjs-ja-translation/chore/update-basic-features-script
Chor: basic-features/script の更新
2 parents e27da30 + 73b9201 commit 1352998

File tree

2 files changed

+220
-0
lines changed

2 files changed

+220
-0
lines changed

‎docs/basic-features/script.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
description: Next.js helps you optimize loading third-party scripts with the built-in next/script component.
3+
---
4+
5+
# Script Component
6+
7+
<details>
8+
<summary><b>Examples</b></summary>
9+
<ul>
10+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/script-component">Script Component</a></li>
11+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-google-tag-manager">Google Tag Manager</a></li>
12+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-google-analytics">Google Analytics</a></li>
13+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-facebook-pixel">Facebook Pixel</a></li>
14+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-clerk">Clerk</a></li>
15+
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/with-segment-analytics">Segment Analytics</a></li>
16+
</ul>
17+
</details>
18+
19+
<details>
20+
<summary><b>Version History</b></summary>
21+
22+
| Version | Changes |
23+
| --------- | ------------------------- |
24+
| `v11.0.0` | `next/script` introduced. |
25+
26+
</details>
27+
28+
The Next.js Script component, [`next/script`](/docs/api-reference/next/script.md), is an extension of the HTML `<script>` element. It enables developers to set the loading priority of third-party scripts anywhere in their application without needing to append directly to `next/head`, saving developer time while improving loading performance.
29+
30+
```jsx
31+
import Script from 'next/script'
32+
33+
export default function Home() {
34+
return (
35+
<>
36+
<Script src="https://www.google-analytics.com/analytics.js" />
37+
</>
38+
)
39+
}
40+
```
41+
42+
## Overview
43+
44+
Websites often use third-party scripts to include different types of functionality into their site, such as analytics, ads, customer support widgets, and consent management. However, this can introduce problems that impact both user and developer experience:
45+
46+
- Some third-party scripts are heavy on loading performance and can drag down the user experience, especially if they are render-blocking and delay any page content from loading
47+
- Developers often struggle to decide where to place third-party scripts in an application to ensure optimal loading
48+
49+
The Script component makes it easier for developers to place a third-party script anywhere in their application while taking care of optimizing its loading strategy.
50+
51+
## Usage
52+
53+
To add a third-party script to your application, import the `next/script` component:
54+
55+
```jsx
56+
import Script from 'next/script'
57+
```
58+
59+
### Strategy
60+
61+
With `next/script`, you decide when to load your third-party script by using the `strategy` property:
62+
63+
```jsx
64+
<Script src="https://connect.facebook.net/en_US/sdk.js" strategy="lazyOnload" />
65+
```
66+
67+
There are three different loading strategies that can be used:
68+
69+
- `beforeInteractive`: Load before the page is interactive
70+
- `afterInteractive`: (**default**): Load immediately after the page becomes interactive
71+
- `lazyOnload`: Load during idle time
72+
73+
#### beforeInteractive
74+
75+
Scripts that load with the `beforeInteractive` strategy are injected into the initial HTML from the server and run before self-bundled JavaScript is executed. This strategy should be used for any critical scripts that need to be fetched and executed before the page is interactive.
76+
77+
```jsx
78+
<Script
79+
src="https://cdn.jsdelivr.net/npm/cookieconsent@3/build/cookieconsent.min.js"
80+
strategy="beforeInteractive"
81+
/>
82+
```
83+
84+
Examples of scripts that should be loaded as soon as possible with this strategy include:
85+
86+
- Bot detectors
87+
- Cookie consent managers
88+
89+
#### afterInteractive
90+
91+
Scripts that use the `afterInteractive` strategy are injected client-side and will run after Next.js hydrates the page. This strategy should be used for scripts that do not need to load as soon as possible and can be fetched and executed immediately after the page is interactive.
92+
93+
```jsx
94+
<Script
95+
strategy="afterInteractive"
96+
dangerouslySetInnerHTML={{
97+
__html: `
98+
(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
99+
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
100+
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
101+
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
102+
})(window,document,'script','dataLayer', 'GTM-XXXXXX');
103+
`,
104+
}}
105+
/>
106+
```
107+
108+
Examples of scripts that are good candidates to load immediately after the page becomes interactive include:
109+
110+
- Tag managers
111+
- Analytics
112+
113+
#### lazyOnload
114+
115+
Scripts that use the `lazyOnload` strategy are loaded late after all resources have been fetched and during idle time. This strategy should be used for background or low priority scripts that do not need to load before or immediately after a page becomes interactive.
116+
117+
```jsx
118+
<Script src="https://connect.facebook.net/en_US/sdk.js" strategy="lazyOnload" />
119+
```
120+
121+
Examples of scripts that do not need to load immediately and can be lazy-loaded include:
122+
123+
- Chat support plugins
124+
- Social media widgets
125+
126+
### Inline Scripts
127+
128+
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:
129+
130+
```jsx
131+
<Script id="show-banner" strategy="lazyOnload">
132+
{`document.getElementById('banner').classList.remove('hidden')`}
133+
</Script>
134+
```
135+
136+
Or by using the `dangerouslySetInnerHTML` property:
137+
138+
```jsx
139+
<Script
140+
id="show-banner"
141+
dangerouslySetInnerHTML={{
142+
__html: `document.getElementById('banner').classList.remove('hidden')`,
143+
}}
144+
/>
145+
```
146+
147+
There are two limitations to be aware of when using the Script component for inline scripts:
148+
149+
- Only the `afterInteractive` and `lazyOnload` strategies can be used. The `beforeInteractive` loading strategy injects the contents of an external script into the initial HTML response. Inline scripts already do this, which is why **the `beforeInteractive` strategy cannot be used with inline scripts.**
150+
- An `id` attribute must be defined in order for Next.js to track and optimize the script
151+
152+
### Executing Code After Loading (`onLoad`)
153+
154+
Some third-party scripts require users to run JavaScript code after the script has finished loading in order to instantiate content or call a function. If you are loading a script with either `beforeInteractive` or `afterInteractive` as a loading strategy, you can execute code after it has loaded using the `onLoad` property:
155+
156+
```jsx
157+
import { useState } from 'react'
158+
import Script from 'next/script'
159+
160+
export default function Home() {
161+
const [stripe, setStripe] = useState(null)
162+
163+
return (
164+
<>
165+
<Script
166+
id="stripe-js"
167+
src="https://js.stripe.com/v3/"
168+
onLoad={() => {
169+
setStripe({ stripe: window.Stripe('pk_test_12345') })
170+
}}
171+
/>
172+
</>
173+
)
174+
}
175+
```
176+
177+
Sometimes it is helpful to catch when a script fails to load. These errors can be handled with the `onError` property:
178+
179+
```jsx
180+
import Script from 'next/script'
181+
182+
export default function Home() {
183+
return (
184+
<>
185+
<Script
186+
id="will-fail"
187+
src="https://example.com/non-existant-script.js"
188+
onError={(e) => {
189+
console.error('Script failed to load', e)
190+
}}
191+
/>
192+
</>
193+
)
194+
}
195+
```
196+
197+
### Additional Attributes
198+
199+
There are many DOM attributes that can be assigned to a `<script>` element that are not used by the Script component, like [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) or [custom data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*). Including any additional attributes will automatically forward it to the final, optimized `<script>` element that is outputted to the page.
200+
201+
```jsx
202+
import Script from 'next/script'
203+
204+
export default function Home() {
205+
return (
206+
<>
207+
<Script
208+
src="https://www.google-analytics.com/analytics.js"
209+
id="analytics"
210+
nonce="XUENAJFW"
211+
data-test="analytics"
212+
/>
213+
</>
214+
)
215+
}
216+
```

‎docs/manifest.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,10 @@
9696
{
9797
"title": "サポートしているブラウザと機能",
9898
"path": "/docs/basic-features/supported-browsers-features.md"
99+
},
100+
{
101+
"title": "Handling Scripts",
102+
"path": "/docs/basic-features/script.md"
99103
}
100104
]
101105
},

0 commit comments

Comments
 (0)