スクリプト
このAPIリファレンスは、Scriptコンポーネントで利用可能なpropsの使い方を理解するのに役立ちます。機能と使用方法については、スクリプトの最適化ページをご覧ください。
import Script from 'next/script'
export default function Dashboard() {
return (
<>
<Script src="https://example.com/script.js" />
</>
)
}
Props
Scriptコンポーネントで利用可能なpropsの概要です:
Prop | 例 | 型 | 必須 |
---|---|---|---|
src | src="http://example.com/script" | String | インラインスクリプトを使用しない限り必須 |
strategy | strategy="lazyOnload" | String | - |
onLoad | onLoad={onLoadFunc} | Function | - |
onReady | onReady={onReadyFunc} | Function | - |
onError | onError={onErrorFunc} | Function | - |
必須Props
<Script />
コンポーネントには以下のプロパティが必要です。
src
外部スクリプトのURLを指定するパス文字列。これは絶対的な外部URLまたは内部パスのいずれかです。インラインスクリプトを使用しない限り、src
プロパティは必須です。
オプションProps
<Script />
コンポーネントは、必須のものに加えていくつかの追加プロパティを受け入れます。
strategy
スクリプトの読み込み戦略です。使用できる4つの異なる戦略があります:
beforeInteractive
: Next.jsのコードの前、およびページのハイドレーションが発生する前に読み込みます。afterInteractive
: (デフォルト) ページでのハイドレーションが一部発生した後、早い段階で読み込みます。lazyOnload
: ブラウザのアイドル時間中に読み込みます。worker
: (実験的) Webワーカーで読み込みます。
beforeInteractive
beforeInteractive
戦略で読み込まれるスクリプトは、サーバーから初期HTMLに挿入され、Next.jsモジュールの前にダウンロードされ、ページで_いかなる_ハイドレーションが発生する前に配置された順序で実行されます。
この戦略で指定されたスクリプトは、ファーストパーティコードの前にプリロードおよびフェッチされますが、その実行はページのハイドレーションをブロックしません。
beforeInteractive
スクリプトはDocument
コンポーネント(pages/_document.js
)内に配置する必要があり、サイト全体で必要なスクリプトを読み込むように設計されています(つまり、アプリケーション内の任意のページがサーバーサイドで読み込まれたときにスクリプトが読み込まれます)。
この戦略は、ページの一部がインタラクティブになる前にフェッチする必要がある重要なスクリプトにのみ使用すべきです。
import { Html, Head, Main, NextScript } from 'next/document'
import Script from 'next/script'
export default function Document() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
<Script
src="https://example.com/script.js"
strategy="beforeInteractive"
/>
</body>
</Html>
)
}
補足:
beforeInteractive
を持つスクリプトは、コンポーネント内のどこに配置されていても、常にHTMLドキュメントのhead
内に挿入されます。
beforeInteractive
でできるだけ早く読み込むべきスクリプトの例には、以下のようなものがあります:
- ボット検出器
- Cookie同意マネージャー
afterInteractive
afterInteractive
戦略を使用するスクリプトはクライアントサイドのHTMLに挿入され、ページでのハイドレーションが一部(または全部)発生した後に読み込まれます。これはScriptコンポーネントのデフォルト戦略であり、できるだけ早く読み込む必要があるが、ファーストパーティのNext.jsコードの前ではないスクリプトに使用すべきです。
afterInteractive
スクリプトは任意のページやレイアウト内に配置でき、そのページ(またはページのグループ)がブラウザで開かれたときにのみ読み込まれ実行されます。
import Script from 'next/script'
export default function Page() {
return (
<>
<Script src="https://example.com/script.js" strategy="afterInteractive" />
</>
)
}
afterInteractive
に適したスクリプトの例としては以下のようなものがあります:
- タグマネージャー
- アナリティクス
lazyOnload
lazyOnload
戦略を使用するスクリプトはブラウザのアイドル時間中にクライアントサイドのHTMLに挿入され、ページ上のすべてのリソースがフェッチされた後に読み込まれます。この戦略は、早期に読み込む必要のないバックグラウンドまたは優先度の低いスクリプトに使用すべきです。
lazyOnload
スクリプトは任意のページやレイアウト内に配置でき、そのページ(またはページのグループ)がブラウザで開かれたときにのみ読み込まれ実行されます。
import Script from 'next/script'
export default function Page() {
return (
<>
<Script src="https://example.com/script.js" strategy="lazyOnload" />
</>
)
}
すぐに読み込む必要がなく、lazyOnload
でフェッチできるスクリプトの例としては以下のようなものがあります:
- チャットサポートプラグイン
- ソーシャルメディアウィジェット
worker
注意:
worker
戦略はまだ安定しておらず、Appルーターではまだ機能していません。慎重に使用してください。
worker
戦略を使用するスクリプトはWebワーカーにオフロードされ、メインスレッドを解放し、重要なファーストパーティリソースのみがそこで処理されるようにします。この戦略は任意のスクリプトに使用できますが、すべてのサードパーティスクリプトをサポートすることを保証しない高度なユースケースです。
戦略としてworker
を使用するには、next.config.js
でnextScriptWorkers
フラグを有効にする必要があります:
module.exports = {
experimental: {
nextScriptWorkers: true,
},
}
worker
スクリプトは現在、pages/
ディレクトリでのみ使用できます:
import Script from 'next/script'
export default function Home() {
return (
<>
<Script src="https://example.com/script.js" strategy="worker" />
</>
)
}
onLoad
注意:
onLoad
はまだサーバーコンポーネントでは機能せず、クライアントコンポーネントでのみ使用できます。さらに、onLoad
はbeforeInteractive
と一緒に使用できません - 代わりにonReady
の使用を検討してください。
一部のサードパーティスクリプトでは、スクリプトの読み込みが完了した後にコンテンツをインスタンス化したり関数を呼び出したりするためのJavaScriptコードを実行する必要があります。読み込み戦略としてafterInteractive
またはlazyOnload
を使用してスクリプトを読み込む場合、onLoad
プロパティを使用して読み込み後にコードを実行できます。
以下は、ライブラリが読み込まれた後にのみlodashメソッドを実行する例です。
'use client'
import Script from 'next/script'
export default function Page() {
return (
<>
<Script
src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.20/lodash.min.js"
onLoad={() => {
console.log(_.sample([1, 2, 3, 4]))
}}
/>
</>
)
}
onReady
注意:
onReady
はまだサーバーコンポーネントでは機能せず、クライアントコンポーネントでのみ使用できます。
一部のサードパーティスクリプトでは、スクリプトの読み込みが完了した後、およびコンポーネントがマウントされるたびに(例えばルートナビゲーション後に)JavaScriptコードを実行する必要があります。onReady
プロパティを使用すると、スクリプトが最初に読み込まれたときのロードイベント後、およびその後のコンポーネントの再マウントごとにコードを実行できます。
以下は、コンポーネントがマウントされるたびにGoogle Maps JSの埋め込みを再インスタンス化する方法の例です:
import { useRef } from 'react'
import Script from 'next/script'
export default function Page() {
const mapRef = useRef()
return (
<>
<div ref={mapRef}></div>
<Script
id="google-maps"
src="https://maps.googleapis.com/maps/api/js"
onReady={() => {
new google.maps.Map(mapRef.current, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
})
}}
/>
</>
)
}
onError
注意:
onError
はまだサーバーコンポーネントでは機能せず、クライアントコンポーネントでのみ使用できます。onError
はbeforeInteractive
読み込み戦略では使用できません。
スクリプトの読み込みに失敗した場合にキャッチすると便利な場合があります。これらのエラーはonError
プロパティで処理できます:
import Script from 'next/script'
export default function Page() {
return (
<>
<Script
src="https://example.com/script.js"
onError={(e: Error) => {
console.error('Script failed to load', e)
}}
/>
</>
)
}
バージョン履歴
バージョン | 変更点 |
---|---|
v13.0.0 | beforeInteractive とafterInteractive がapp をサポートするように修正。 |
v12.2.4 | onReady propが追加。 |
v12.2.2 | beforeInteractive を持つnext/script を_document に配置できるようになりました。 |
v11.0.0 | next/script が導入。 |