Version 12

버전 12 으로 업그레이드하려면 아래의 커맨드를 실행하세요:

npm i next@12 react@17 react-dom@17 eslint-config-next@12
 
yarn add next@12 react@17 react-dom@17 eslint-config-next@12
 
pnpm up next@12 react@17 react-dom@17 eslint-config-next@12
 
bun add next@12 react@17 react-dom@17 eslint-config-next@12

알아두면 좋은 사항: TypeScript를 사용하는 경우, @types/react 및 @types/react-dom도 해당 버전으로 업그레이드해야 합니다.

Upgrading to 12.2

Middleware - 12.2 이전에 Middleware를 사용한 경우, 자세한 내용은 업그레이드 가이드를 참조하세요.

Upgrading to 12.0

Minimum Node.js Version (opens in a new tab) - 최소 Node.js 버전이 12.0.0에서 12.22.0으로 상향 조정되었습니다. 이는 Node.js의 첫 번째 네이티브 ES 모듈 지원 버전입니다.

Minimum React Version (opens in a new tab) - 최소 요구 React 버전은 17.0.2입니다. 업그레이드하려면 터미널에서 다음 명령어를 실행할 수 있습니다:

npm install react@latest react-dom@latest
 
yarn add react@latest react-dom@latest
 
pnpm update react@latest react-dom@latest
 
bun add react@latest react-dom@latest

SWC replacing Babel

Next.js는 이제 Rust 기반 컴파일러인 SWC (opens in a new tab)를 사용하여 JavaScript/TypeScript를 컴파일합니다. 이 새로운 컴파일러는 개별 파일을 컴파일할 때 Babel보다 최대 17배 빠르고, Fast Refresh에서는 최대 5배 빠릅니다.

Next.js는 커스텀 Babel 구성을 가진 애플리케이션과의 완전한 하위 호환성을 제공합니다. Next.js가 기본적으로 처리하는 styled-jsx 및 getStaticProps / getStaticPaths / getServerSideProps의 트리 쉐이킹과 같은 모든 변환은 Rust로 포팅되었습니다.

애플리케이션이 커스텀 Babel 구성을 가지고 있는 경우, Next.js는 JavaScript/Typescript를 컴파일할 때 SWC 대신 Babel을 사용하도록 자동으로 옵트아웃됩니다.

현재 커스텀 Babel 변환이 필요한 외부 라이브러리와의 많은 통합은 가까운 미래에 Rust 기반 SWC 변환으로 포팅될 예정입니다. 여기에는 다음이 포함되지만 이에 국한되지 않습니다:

Styled Components
Emotion
Relay

SWC 채택을 도울 수 있는 변환을 우선시하기 위해, 이 피드백 스레드 (opens in a new tab)에 .babelrc를 제공해주세요.

SWC replacing Terser for minification

JavaScript를 최대 7배 빠르게 압축하기 위해 next.config.js에서 플래그를 사용하여 Terser를 SWC로 교체할 수 있습니다:

next.config.js

module.exports = {
  swcMinify: true,
}

SWC를 사용한 압축은 Next.js 12.1에서 기본값이 되기 전에 더 많은 실제 Next.js 애플리케이션에 대해 테스트할 수 있도록 옵트인 플래그입니다. 압축에 대한 피드백이 있는 경우, 이 피드백 스레드 (opens in a new tab)에 남겨주세요.

Improvements to styled-jsx CSS parsing

Rust 기반 컴파일러 외에도 styled-jsx Babel 변환에 사용된 새로운 CSS 파서를 구현했습니다. 이 새로운 파서는 CSS 처리 능력을 개선했으며, 이전에는 잘못된 CSS가 통과되어 예기치 않은 동작을 유발할 수 있었던 경우를 오류로 처리합니다.

이 변경으로 인해 잘못된 CSS는 개발 중 및 next build 중에 오류를 발생시킵니다. 이 변경은 styled-jsx 사용에만 영향을 미칩니다.

`next/image` changed wrapping element

next/image는 이제 <div> 대신 <span> 내부에 <img>를 렌더링합니다.

애플리케이션에 .container span과 같은 span을 타겟팅하는 특정 CSS가 있는 경우, Next.js 12로 업그레이드하면 <Image> 컴포넌트 내부의 래핑 요소가 잘못 일치할 수 있습니다. 이 문제를 피하려면 .container span.item과 같이 선택기를 특정 클래스에 제한하고 해당 클래스 이름으로 관련 컴포넌트를 업데이트하세요, 예를 들어 <span className="item" />.

애플리케이션에 next/image <div> 태그를 타겟팅하는 특정 CSS가 있는 경우, 예를 들어 .container div, 더 이상 일치하지 않을 수 있습니다. 선택기를 .container span으로 업데이트하거나, 선호되는 방법으로 <Image> 컴포넌트를 래핑하는 새로운 <div className="wrapper">를 추가하고 이를 타겟팅하세요, 예를 들어 .container .wrapper.

className prop은 변경되지 않으며, 여전히 기본 <img> 요소에 전달됩니다.

자세한 내용은 문서를 참조하세요.

HMR connection now uses a WebSocket

이전에는 Next.js가 HMR 이벤트를 수신하기 위해 server-sent events (opens in a new tab) 연결을 사용했습니다. Next.js 12는 이제 WebSocket 연결을 사용합니다.

Next.js dev 서버로 요청을 프록시할 때 업그레이드 요청이 올바르게 처리되도록 해야 할 경우가 있습니다. 예를 들어, nginx에서 다음 구성을 추가해야 합니다:

location /_next/webpack-hmr {
    proxy_pass http://localhost:3000/_next/webpack-hmr;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Apache (2.x)를 사용하는 경우, 서버에 웹 소켓을 활성화하려면 다음 구성을 추가할 수 있습니다. 포트, 호스트 이름 및 서버 이름을 검토하세요.

<VirtualHost *:443>
 # ServerName yourwebsite.local
 ServerName "${WEBSITE_SERVER_NAME}"
 ProxyPass / http://localhost:3000/
 ProxyPassReverse / http://localhost:3000/
 # Next.js 12 uses websocket
 <Location /_next/webpack-hmr>
    RewriteEngine On
    RewriteCond %{QUERY_STRING} transport=websocket [NC]
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule /(.*) ws://localhost:3000/_next/webpack-hmr/$1 [P,L]
    ProxyPass ws://localhost:3000/_next/webpack-hmr retry=0 timeout=30
    ProxyPassReverse ws://localhost:3000/_next/webpack-hmr
 </Location>
</VirtualHost>

express와 같은 커스텀 서버의 경우, 요청이 올바르게 전달되도록 app.all을 사용해야 할 수 있습니다. 예를 들어:

app.all('/_next/webpack-hmr', (req, res) => {
  nextjsRequestHandler(req, res)
})

Webpack 4 support has been removed

이미 webpack 5를 사용 중인 경우, 이 섹션을 건너뛸 수 있습니다.

Next.js는 Next.js 11에서 기본 컴파일러로 webpack 5를 채택했습니다. webpack 5 업그레이드 문서에 명시된 바와 같이 Next.js 12는 webpack 4에 대한 지원을 제거합니다.

opt-out 플래그를 사용하여 여전히 webpack 4를 사용 중인 애플리케이션의 경우, 이제 webpack 5 업그레이드 문서로 연결되는 오류가 표시됩니다.

`target` option deprecated

next.config.js에 target이 없는 경우, 이 섹션을 건너뛸 수 있습니다.

target 옵션은 페이지를 실행하는 데 필요한 종속성을 추적하는 기본 제공 지원으로 대체되었습니다.

next build 중에 Next.js는 각 페이지와 해당 종속성을 자동으로 추적하여 애플리케이션의 프로덕션 버전을 배포하는 데 필요한 모든 파일을 결정합니다.

현재 serverless로 설정된 target 옵션을 사용하는 경우, 새로운 출력 활용 방법에 대한 문서를 읽어보세요.

Version 13 Version 11