[ Components ] <Script/>

차차·2023년 6월 15일

목록 보기

33/34

// app/dashboard/page.tsx

import Script from 'next/script'
 
export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}

Props

아래는 <Script>에서 사용 가능한 요소들이다.

Prop	Example	Type	Required
https://nextjs.org/docs/app/api-reference/components/script#src	src="http://example.com/script"	String	Required unless inline script is used
https://nextjs.org/docs/app/api-reference/components/script#strategy	strategy="lazyOnload"	String	-
https://nextjs.org/docs/app/api-reference/components/script#onload	onLoad={onLoadFunc}	Function	-
https://nextjs.org/docs/app/api-reference/components/script#onready	onReady={onReadyFunc}	Function	-
https://nextjs.org/docs/app/api-reference/components/script#onerror	onError={onErrorFunc}	Function	-

필수적인 Props

<Script /> 컴포넌트는 다음과 같은 속성이 필요하다.

src

외부 스크립트의 URL을 지정하는 경로 문자열이다. 이는 절대 외부 URL이나 내부 경로일 수 있다. src 속성은 인라인 스크립트를 사용하지 않는 한 필수다.

선택적인 Props

아래는 <Script /> 의 선택적인 요소들이다.

strategy

스크립트의 로딩 전략이다. 사용할 수 있는 네 가지 다른 전략이 있다.

beforeInteractive : Next.js 코드 및 페이지 하이드레이션 이전에 로드된다.
afterInteractive : (default) 일부 하이드레이션 이후에 로드된다.
lazyOnload : 브라우저가 비활성 상태일 때 로드된다.
worker : (실험적인) 웹 워커에서 로드된다.

`beforInteractive`

beforeInteractive 전략으로 로드되는 스크립트는 초기에 서버로부터 HTML에 삽입되며, Next.js 모듈 이전에 다운로드되고 페이지 하이드레이션 이전에 순서대로 실행된다.

이 전략으로 표시된 스크립트는 처음부터 사전로드되고 가져와진다. 그러나 실행은 페이지 하이드레이션을 차단하지 않는다.

beforeInteractive 스크립트는 루트 레이아웃(app/layout.tsx) 내에 배치되어야 하며, 전체 사이트에서 필요한 스크립트를 로드하는 데 사용된다 (즉, 응용 프로그램의 어떤 페이지가 서버 측에서 로드되었을 때 스크립트가 로드된다).

이 전략은 페이지의 어떤 부분이 상호 작용 가능해지기 전에 가져와야 하는 중요한 스크립트에만 사용해야 한다.

beforeInteractive로 설정된 스크립트는 컴포넌트 내에서 어디에 배치되었는지와 상관없이 항상 HTML 문서의 헤드(head)에 삽입된다.

// app/layout.tsx

import Script from 'next/script'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <Script
        src="https://example.com/script.js"
        strategy="beforeInteractive"
      />
    </html>
  )
}

beforeInteractive를 사용하여 가능한 빨리 로드되어야 하는 몇 가지 스크립트의 예시는 다음과 같다.

봇 감지기 (Bot detectors)
쿠키 동의 관리자 (Cookie consent managers)

`afterInteractive`

afterInteractive 전략을 사용하는 스크립트는 HTML에 클라이언트 측에서 삽입되며, 페이지의 일부 (또는 전체) 하이드레이션 이후에 로드된다. 이것은 Script 컴포넌트의 기본 전략이며, 가능한 빨리 로드되어야 하지만 first-party Next.js 코드 이전에는 로드되지 않아야 하는 스크립트에 사용해야 한다.

afterInteractive 스크립트는 어떤 페이지나 레이아웃에도 배치할 수 있으며, 해당 페이지 (또는 페이지 그룹)가 브라우저에서 열릴 때만 로드되고 실행된다.

// app/page.js

import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  )
}

afterInteractive에 적합한 스크립트의 몇 가지 예시는 다음과 같다.

태그 관리자 (Tag managers)
분석 도구 (Analytics)

`lazyOnload`

lazyOnload 전략을 사용하는 스크립트는 브라우저가 비활성 상태일 때 HTML에 클라이언트 측에서 삽입되며, 페이지의 모든 리소스가 가져온 후에 로드된다. 이 전략은 조금 뒤에 로드되어도 되는 백그라운드 또는 우선순위가 낮은 스크립트에 사용해야 한다.

lazyOnload 스크립트는 어떤 페이지나 레이아웃에도 배치할 수 있으며, 해당 페이지 (또는 페이지 그룹)가 브라우저에서 열릴 때만 로드되고 실행된다.

import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="lazyOnload" />
    </>
  )
}

즉시 로드할 필요가 없고 lazyOnload로 가져올 수 있는 스크립트의 예시로는 다음이 있습니다:

채팅 지원 플러그인 (Chat support plugins)
소셜 미디어 위젯 (Social media widgets)

`worker`

worker 전략은 아직 안정화되지 않았으며, app 디렉토리에서는 아직 작동하지 않는다.

worker 전략을 사용하는 스크립트는 주 스레드에서 벗어나 웹 워커로 전달되어 주 스레드를 해제하고 중요한 first-party 리소스만 처리되도록 한다. 이 전략은 모든 스크립트에 사용할 수 있지만, 모든 타사 스크립트를 지원하는 것이 보장되지 않는 고급 사용 사례다.

전략으로 worker를 사용하려면 next.config.js에서 nextScriptWorkers 플래그를 활성화해야 한다.

// next.config.js

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

현재 worker 스크립트는 pages/ 디렉토리에서만 사용할 수 있다.

// pages/home.tsx

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 라이브러리가 로드된 후에만 lodash 메서드를 실행하는 예시다.

// app/page.tsx

'use client'
 
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,
          })
        }}
      />
    </>
  )
}

`onReady`

onReady는 아직 Server Components에서 작동하지 않으며, Client Components에서만 사용할 수 있다.

일부 타사 스크립트는 스크립트가 로드되고 컴포넌트가 재마운트될 때마다 (예: 라우트 이동 후) 사용자가 JavaScript 코드를 실행해야 하는 경우가 있다. onReady 속성을 사용하여 스크립트가 처음 로드될 때와 이후의 모든 컴포넌트 재마운트 후에 코드를 실행할 수 있다.

다음은 컴포넌트가 재마운트될 때마다 Google Maps JS embed를 다시 인스턴스화하는 예시다.

// app/page.tsx

'use client'
 
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는 아직 Server Components에서 작동하지 않으며, Client Components에서만 사용할 수 있다. onError는 beforeInteractive 로딩 전략과 함께 사용할 수 없다.

때로는 스크립트 로드에 실패했을 때 이를 감지하는 것이 유용할 수 있다. onError 속성을 사용하여 이러한 오류를 처리할 수 있다.

// app/page.tsx

'use client'
 
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)
        }}
      />
    </>
  )
}