Unverified Commit a8186065 authored by Houssein Djirdeh's avatar Houssein Djirdeh Committed by GitHub

[Script] Adds `onReady` prop to `next/script` (#38849)

Closes: #30962

This PR adds a new `onReady` prop to `next/script` to handle shortcomings of the current `onLoad` prop. Some third-party providers and widgets require initialization code to run after the script's `load` event and every time the component is mounted. The `onReady` should solve that use case.

For more details, refer to the discussion in #30962.

CC @janicklas-ralph

## Bug

- [X] Related issues linked using `fixes #number`
- [X] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`
Co-authored-by: 's avatarJJ Kasper <22380829+ijjk@users.noreply.github.com>
parent 85b00b2c
...@@ -20,6 +20,7 @@ description: Optimize loading of third-party scripts with the built-in Script co ...@@ -20,6 +20,7 @@ description: Optimize loading of third-party scripts with the built-in Script co
| Version | Changes | | Version | Changes |
| --------- | ------------------------- | | --------- | ------------------------- |
| `v12.2.4` | `onReady` prop added. |
| `v11.0.0` | `next/script` introduced. | | `v11.0.0` | `next/script` introduced. |
</details> </details>
...@@ -47,9 +48,9 @@ The loading strategy of the script. ...@@ -47,9 +48,9 @@ The loading strategy of the script.
### onLoad ### onLoad
A method that returns additional JavaScript that should be executed after the script has finished loading. A method that returns additional JavaScript that should be executed once after the script has finished loading.
> **Note: `onLoad` can't be used with the `beforeInteractive` loading strategy.** > **Note: `onLoad` can't be used with the `beforeInteractive` loading strategy. Consider using `onReady` instead.**
The following is an example of how to use the `onLoad` property: The following is an example of how to use the `onLoad` property:
...@@ -74,6 +75,34 @@ export default function Home() { ...@@ -74,6 +75,34 @@ export default function Home() {
} }
``` ```
### onReady
A method that returns additional JavaScript that should be executed after the script has finished loading and every time the component is mounted.
The following is an example of how to use the `onReady` property:
```jsx
import { useState } from 'react'
import Script from 'next/script'
export default function Home() {
return (
<>
<Script
id="google-maps"
src="https://maps.googleapis.com/maps/api/js"
onReady={() => {
new google.maps.Map(ref.current, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
})
}}
/>
</>
)
}
```
### onError ### onError
A method that executes if the script fails to load. A method that executes if the script fails to load.
......
...@@ -21,6 +21,7 @@ description: Next.js helps you optimize loading third-party scripts with the bui ...@@ -21,6 +21,7 @@ description: Next.js helps you optimize loading third-party scripts with the bui
| Version | Changes | | Version | Changes |
| --------- | ------------------------- | | --------- | ------------------------- |
| `v12.2.4` | `onReady` prop added. |
| `v11.0.0` | `next/script` introduced. | | `v11.0.0` | `next/script` introduced. |
</details> </details>
...@@ -249,9 +250,9 @@ The `id` property is required for **inline scripts** in order for Next.js to tra ...@@ -249,9 +250,9 @@ The `id` property is required for **inline scripts** in order for Next.js to tra
### Executing Code After Loading (`onLoad`) ### Executing Code After Loading (`onLoad`)
> **Note: `onLoad` and `onError` cannot be used with the `beforeInteractive` loading strategy.** > **Note: `onLoad` cannot be used with the `beforeInteractive` loading strategy. Consider using `onReady` instead.**
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 `afterInteractive` or `lazyOnload` as a loading strategy, you can execute code after it has loaded using the `onLoad` property: Some third-party scripts require users to run JavaScript code once after the script has finished loading in order to instantiate content or call a function. If you are loading a script with either `afterInteractive` or `lazyOnload` as a loading strategy, you can execute code after it has loaded using the `onLoad` property:
```jsx ```jsx
import { useState } from 'react' import { useState } from 'react'
...@@ -274,6 +275,35 @@ export default function Home() { ...@@ -274,6 +275,35 @@ export default function Home() {
} }
``` ```
### Executing Code After Mounting (`onReady`)
Some third-party scripts require users to run JavaScript code after the script has finished loading and every time the component is mounted (after a route navigation for example). You can execute code after the script's `load` event when it first loads and then after every subsequent component re-mount using the `onReady` property:
```jsx
import Script from 'next/script'
export default function Home() {
return (
<>
<Script
id="google-maps"
src="https://maps.googleapis.com/maps/api/js"
onReady={() => {
new google.maps.Map(ref.current, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
})
}}
/>
</>
)
}
```
### Handling errors (`onError`)
> **Note: `onError` cannot be used with the `beforeInteractive` loading strategy.**
Sometimes it is helpful to catch when a script fails to load. These errors can be handled with the `onError` property: Sometimes it is helpful to catch when a script fails to load. These errors can be handled with the `onError` property:
```jsx ```jsx
......
...@@ -11,6 +11,7 @@ export interface ScriptProps extends ScriptHTMLAttributes<HTMLScriptElement> { ...@@ -11,6 +11,7 @@ export interface ScriptProps extends ScriptHTMLAttributes<HTMLScriptElement> {
strategy?: 'afterInteractive' | 'lazyOnload' | 'beforeInteractive' | 'worker' strategy?: 'afterInteractive' | 'lazyOnload' | 'beforeInteractive' | 'worker'
id?: string id?: string
onLoad?: (e: any) => void onLoad?: (e: any) => void
onReady?: () => void | null
onError?: (e: any) => void onError?: (e: any) => void
children?: React.ReactNode children?: React.ReactNode
} }
...@@ -22,6 +23,7 @@ export type Props = ScriptProps ...@@ -22,6 +23,7 @@ export type Props = ScriptProps
const ignoreProps = [ const ignoreProps = [
'onLoad', 'onLoad',
'onReady',
'dangerouslySetInnerHTML', 'dangerouslySetInnerHTML',
'children', 'children',
'onError', 'onError',
...@@ -33,6 +35,7 @@ const loadScript = (props: ScriptProps): void => { ...@@ -33,6 +35,7 @@ const loadScript = (props: ScriptProps): void => {
src, src,
id, id,
onLoad = () => {}, onLoad = () => {},
onReady = null,
dangerouslySetInnerHTML, dangerouslySetInnerHTML,
children = '', children = '',
strategy = 'afterInteractive', strategy = 'afterInteractive',
...@@ -62,6 +65,10 @@ const loadScript = (props: ScriptProps): void => { ...@@ -62,6 +65,10 @@ const loadScript = (props: ScriptProps): void => {
if (onLoad) { if (onLoad) {
onLoad.call(this, e) onLoad.call(this, e)
} }
// Run onReady for the first time after load event
if (onReady) {
onReady()
}
}) })
el.addEventListener('error', function (e) { el.addEventListener('error', function (e) {
reject(e) reject(e)
...@@ -147,8 +154,10 @@ export function initScriptLoader(scriptLoaderItems: ScriptProps[]) { ...@@ -147,8 +154,10 @@ export function initScriptLoader(scriptLoaderItems: ScriptProps[]) {
function Script(props: ScriptProps): JSX.Element | null { function Script(props: ScriptProps): JSX.Element | null {
const { const {
id,
src = '', src = '',
onLoad = () => {}, onLoad = () => {},
onReady = null,
strategy = 'afterInteractive', strategy = 'afterInteractive',
onError, onError,
...restProps ...restProps
...@@ -157,6 +166,15 @@ function Script(props: ScriptProps): JSX.Element | null { ...@@ -157,6 +166,15 @@ function Script(props: ScriptProps): JSX.Element | null {
// Context is available only during SSR // Context is available only during SSR
const { updateScripts, scripts, getIsSsr } = useContext(HeadManagerContext) const { updateScripts, scripts, getIsSsr } = useContext(HeadManagerContext)
useEffect(() => {
const cacheKey = id || src
// Run onReady if script has loaded before but component is re-mounted
if (onReady && cacheKey && LoadCache.has(cacheKey)) {
onReady()
}
}, [onReady, id, src])
useEffect(() => { useEffect(() => {
if (strategy === 'afterInteractive') { if (strategy === 'afterInteractive') {
loadScript(props) loadScript(props)
...@@ -169,8 +187,10 @@ function Script(props: ScriptProps): JSX.Element | null { ...@@ -169,8 +187,10 @@ function Script(props: ScriptProps): JSX.Element | null {
if (updateScripts) { if (updateScripts) {
scripts[strategy] = (scripts[strategy] || []).concat([ scripts[strategy] = (scripts[strategy] || []).concat([
{ {
id,
src, src,
onLoad, onLoad,
onReady,
onError, onError,
...restProps, ...restProps,
}, },
...@@ -178,7 +198,7 @@ function Script(props: ScriptProps): JSX.Element | null { ...@@ -178,7 +198,7 @@ function Script(props: ScriptProps): JSX.Element | null {
updateScripts(scripts) updateScripts(scripts)
} else if (getIsSsr && getIsSsr()) { } else if (getIsSsr && getIsSsr()) {
// Script has already loaded during SSR // Script has already loaded during SSR
LoadCache.add(restProps.id || src) LoadCache.add(id || src)
} else if (getIsSsr && !getIsSsr()) { } else if (getIsSsr && !getIsSsr()) {
loadScript(props) loadScript(props)
} }
......
import Script from 'next/script'
import Link from 'next/link'
const url =
'https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js'
const Page = () => {
return (
<div class="container">
<Link href="/page9">Page 9</Link>
<div id="text"></div>
<Script
src={url}
id="script1"
onReady={() => {
// eslint-disable-next-line no-undef
document.getElementById('text').textContent += _.repeat('a', 3)
}}
></Script>
</div>
)
}
export default Page
import Link from 'next/link'
const Page = () => {
return (
<>
<Link href="/page8">Page 8</Link>
</>
)
}
export default Page
...@@ -190,6 +190,30 @@ describe('Next.js Script - Primary Strategies', () => { ...@@ -190,6 +190,30 @@ describe('Next.js Script - Primary Strategies', () => {
} }
}) })
it('onReady fires after load event and then on every subsequent re-mount', async () => {
let browser
try {
browser = await webdriver(appPort, '/page8')
const text = await browser.elementById('text').text()
expect(text).toBe('aaa')
// Navigate to different page and back
await browser.waitForElementByCss('[href="/page9"]')
await browser.click('[href="/page9"]')
await browser.waitForElementByCss('[href="/page8"]')
await browser.click('[href="/page8"]')
await browser.waitForElementByCss('.container')
const sameText = await browser.elementById('text').text()
expect(sameText).toBe('aaa') // onReady should fire again
} finally {
if (browser) await browser.close()
}
})
it('priority beforeInteractive with inline script', async () => { it('priority beforeInteractive with inline script', async () => {
const html = await renderViaHTTP(appPort, '/page5') const html = await renderViaHTTP(appPort, '/page5')
const $ = cheerio.load(html) const $ = cheerio.load(html)
......
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