NextJS API: next/script

hwisaac·2023년 3월 13일

FE nextjs 문서

next/script

Props

NextJS API(page router)

목록 보기

8/10

next/script

이 API 참조 페이지는 Script 컴포넌트에 사용 가능한 props를 이해하는 데 도움이 됩니다. 기능 및 사용법은 Optimizing Scripts 페이지를 참조하세요.

import Script from 'next/script';

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

Props

다음은 Script 컴포넌트에 사용 가능한 props의 요약입니다.

Prop	Example	Values	Required
src	src="http://example.com/script"	String	Required unless inline script is used
strategy	strategy="lazyOnload"	String	Optional
onLoad	onLoad={onLoadFunc}	Function	Optional
onReady	onReady={onReadyFunc}	Function	Optional
onError	onError={onErrorFunc}	Function	Optional

필수 Props

<Script /> 컴포넌트는 다음 속성이 필요합니다.

src

외부 스크립트의 URL을 지정하는 경로 문자열입니다. 절대적인 외부 URL 또는 내부 경로가 될 수 있습니다.

참고: 인라인 스크립트가 사용되지 않는 한 src 속성이 필요합니다.

선택적 Props

<Script /> 컴포넌트에는 필수 사항 이외에도 여러 추가 속성이 허용됩니다.

strategy

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

beforeInteractive: Next.js 코드 및 페이지 수화가 시작되기 전에 로드합니다.
afterInteractive: (기본값) 일부 수화가 이미 발생한 후 조기에 로드합니다.
lazyOnload: 브라우저 유휴 시간 동안 로드합니다.
worker: (실험적) 웹 워커에서 로드합니다.

beforeInteractive

beforeInteractive 전략으로 로드되는 스크립트는 서버에서 초기 HTML에 주입되어, 모든 Next.js 모듈보다 먼저 다운로드되고 페이지 수화가 시작되기 전에 배치된 순서대로 실행됩니다.

이 전략으로 표시된 스크립트는 첫 번째 코드 이전에 사전로드(preloaded)되고 다운로드되지만, 그 실행은 페이지 수화를 방해하지 않습니다.

beforeInteractive 스크립트는 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로 가능한 빨리 로드되어야 하는 몇 가지 예시:

봇 감지기
쿠키 동의 관리자

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로 가져와도 즉시 로드하지 않아도 되는 경우의 예로는 다음과 같은 것이 있습니다:

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

worker

참고: worker 전략은 아직 안정화되지 않았으며 app/ 디렉토리에서 작동하지 않습니다. 주의해서 사용하세요.

worker 전략을 사용하는 스크립트는 웹 워커로 오프로드(off-loaded)되어 주 스레드를 해제하고 중요한 첫 번째 파티 자원만 처리되도록합니다. 이 전략은 모든 스크립트에 사용할 수 있지만 모든 타사 스크립트를 지원하지는 않습니다.

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

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

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

Copy code
import Script from 'next/script';

export default function Home() {
  return (
    <>
      <Script src='https://example.com/script.js' strategy='worker' />
    </>
  );
}

onLoad

참고: beforeInteractive와 함께 onLoad를 사용할 수 없습니다. 대신 onReady를 사용하세요. app/ 디렉토리에서 onLoad 사용법에 대해 자세히 알아보세요.

일부 타사 스크립트는 내용을 인스턴스화하거나 함수를 호출하기 위해 스크립트가 로드된 후에 JavaScript 코드를 실행해야합니다. afterInteractive 또는 lazyOnload와 같은 로딩 전략으로 스크립트를 로드하는 경우 onLoad 속성을 사용하여 로드 후 코드를 실행할 수 있습니다.

다음은 lodash 메서드를 라이브러리가 로드 된 후에만 실행하는 예입니다.

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

참고: beforeInteractive 로딩 전략과 함께 onError를 사용할 수 없습니다. 앱/디렉터리에서 onError의 사용 방법에 대해 더 자세히 알아보세요.

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

import Script from 'next/script';

export default function Page() {
  return (
    <>
      <Script
        src='https://example.com/script.js'
        onError={(e) => {
          console.error('Script failed to load', e);
        }}
      />
    </>
  );
}