

# typedRoutes란?

typedRoutes는 **타입이 보장되는 링크**(statistically typed links)를 실험적으로 지원하는 기능이에요. 이 기능을 사용하려면 Next.js의 App Router를 쓰고, 프로젝트가 TypeScript로 작성되어 있어야 해요.

보통 라우팅할 때, 문자열로 경로를 직접 적다가 오타가 생기거나 경로가 바뀌어도 에러가 나지 않아 나중에 문제를 발견하곤 하죠. 그런데 typedRoutes를 활성화하면, TypeScript가 링크 경로 자체를 타입으로 체크해줘서 이런 실수를 미연에 방지할 수 있어요.

## 설정 방법

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = nextConfig
```

next.config.js 파일에서 `experimental.typedRoutes` 옵션을 `true`로 설정하면 끝!

---

## 추가로 알아두면 좋은 점

- 현재는 실험적 기능이라 안정화가 덜 되었을 수 있어요. 최신 Next.js 버전과 호환되는지 확인이 필요해요.
- App Router가 아닌 예전의 pages 디렉터리 방식에서는 사용할 수 없어요.
- 타입이 자동으로 생성되기 때문에 경로가 바뀌면 바로 코드 내에서 타입 오류를 통해 알려주니 유지보수가 훨씬 수월해집니다.
- 실제로 사용해보면, 링크를 만들 때 `href="/posts/[id]"` 같은 동적 경로를 다룰 때도 타입이 보장되어 편리해요.

Next.js + TypeScript 조합을 쓰시는 분이라면 꼭 한 번 써보길 추천드려요! 프로젝트의 안전성과 생산성이 크게 올라갈 겁니다.

실무에서 필요한 타입스크립트 기반 typedRoutes 활용법

# TypeScript와 Next.js: production 빌드 시 타입 에러 처리하기

Next.js를 사용하다 보면 `next build` 명령어로 프로덕션 빌드를 만들 때, 프로젝트 내에 TypeScript 에러가 있으면 빌드 자체가 실패하는 경우가 있어요. 이는 Next.js가 타입 안정성을 매우 중요하게 여기기 때문인데요.

하지만 만약 여러분이 타입 에러가 있더라도, 빌드를 강제로 진행하고 싶을 때도 있죠. 예를 들어, 배포 파이프라인 안에서 별도로 타입 검사를 돌리고 있다거나, 빌드 중간에 타입 에러가 있어도 어플리케이션을 일단 빌드해봐야 할 때가 있을 수 있어요.

이럴 때는 Next.js의 내장 타입체크 단계를 비활성화하는 방법이 있는데, 이렇게 하면 타입 에러가 있어도 빌드가 계속 진행됩니다. 하지만 이 방법은 정말 "위험한(dangerous)" 방법인 걸 명심해야 해요. 타입 검사를 비활성화하면 의도하지 않은 버그가 프로덕션에 들어갈 수도 있기 때문에, 별도로 타입 체크를 빌드 프로세스나 배포 프로세스에서 꼭 돌려줘야 합니다.

---

## Next.js에서 타입체크 비활성화 방법

`next.config.js`에 아래 설정을 추가해 보세요:

```js
module.exports = {
  typescript: {
    ignoreBuildErrors: true, // 타입 오류가 있어도 빌드를 무시하고 진행
  },
};
```

이 설정을 추가하면 빌드 시 타입 에러가 있어도 에러를 무시하고 빌드가 완료됩니다.

---

## 주의사항

- 위 설정은 개발할 때 임시로 쓰는 용도지, 프로덕션에선 정말 신중하게 사용하세요.
- 무심코 타입 체크를 끄면, 예상치 못한 런타임 오류가 발생할 수 있으니, 별도 CI/CD 파이프라인에서 `tsc --noEmit` 같은 명령으로 타입 검사하는 게 필수입니다.
- 팀 협업 시 타입 검사 설정을 명확히 공유하고, 빌드 실패가 바로 코드 품질 문제로 이어진다는 점을 인지시켜 주세요.

---

## 추가 팁: 타입 체크만 따로 돌리기

Next.js는 `next build`에서 타입 체크와 빌드를 같이 하지만, 타입 체크만 별도로 돌리고 싶으면 명령어를 활용할 수 있어요.

```bash
tsc --noEmit
```

이 명령은 타입 검사만 수행하고, 컴파일 결과물은 만들지 않습니다. 그래서 CI 과정에서 타입 에러를 걸러내는 데 딱 좋아요.

---

### 정리

| 상황                      | 조치 방법                            | 주의사항                            |
|-------------------------|--------------------------------|----------------------------------|
| 타입 에러 있으면 빌드 실패          | 기본 설정 유지                       | 문제가 있으면 빌드 실패로 알려줌             |
| 타입 에러 있어도 빌드 진행하고 싶을 때  | `typescript.ignoreBuildErrors = true` 설정 | 타입 에러 감춰지므로 별도 타입 체크 꼭 할 것   |
| 타입만 별도로 체크하고 싶을 때       | `tsc --noEmit` 명령어 사용            | 빌드 전에 타입 체크를 반드시 수행             |

---

Next.js와 TypeScript를 함께 쓰다 보면 의외로 이런 타입 체크 관련 설정이 꽤 중요한 역할을 해요. 빌드를 무조건 통과시키는 게 좋은 건 아니지만, 상황에 맞게 잘 활용하면 개발 편의성도 올릴 수 있으니 참고하세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

next.config.js 파일을 열어서 typescript 설정에서 ignoreBuildErrors 옵션을 활성화해봅시다:

```js
module.exports = {
  typescript: {
    // !! 주의 !!
    // 타입 에러가 있어도 프로덕션 빌드를 강제로 완료하게 합니다.
    // 실수로 에러를 놓치는 상황이 발생할 수 있으니 신중히 사용하세요!
    ignoreBuildErrors: true,
  },
}
```

---

여기서 잠깐! 이 옵션은 타입스크립트 에러를 무시하고 빌드를 통과시키는 거라, 개발 초기나 빠르게 테스트할 때는 편리하지만, 실제 서비스에 배포할 때는 위험할 수 있어요. 에러가 있는 상태로 배포하면 예상치 못한 버그가 발생할 가능성이 커지니까, 꼭 필요할 때만 사용하고 나중에 에러를 수정하는 걸 추천합니다!

또한, 만약 타입 에러가 계속 발생해서 막히는 상황이라면, 이 옵션 대신 에러를 하나씩 수정하거나 타입 검사 설정을 좀 더 유연하게 조정해보는 것이 더 좋은 방법입니다.

Nextjs 15에서 typescript 제대로 사용하기 

# URL Imports

URL Imports는 아직 실험적인 기능이지만, 외부 서버에서 바로 모듈을 가져와서 사용할 수 있게 해줘요. 보통은 로컬 디스크에서 모듈을 불러오잖아요? 그런데 이 기능을 쓰면 웹 상에 있는 모듈을 직접 불러올 수 있다는 거죠.

> ⚠️ 주의!  
> 이 기능은 불러오는 도메인을 신뢰할 수 있을 때만 사용해야 해요. 악성 코드를 다운로드해서 내 컴퓨터에 실행할 수도 있으니까요. 정식 기능으로 안정화될 때까지는 조심해서 써야 해요.

사용하려면 `next.config.js` 파일에 허용할 URL 접두사를 설정해줘야 해요. 예를 들어:

```js
// next.config.js
module.exports = {
  experimental: {
    urlImports: [
      "https://cdn.skypack.dev/",
      "https://esm.sh/"
    ]
  }
}
```

위처럼 허용할 URL들을 배열로 적어주면, 해당 주소에서 모듈을 바로 불러올 수 있습니다.

---

## URL Imports의 매력 포인트!

- **빠르게 외부 라이브러리 디펜던시 추가**: `npm install` 없이도 외부 CDN에서 바로 모듈을 가져와 개발할 수 있어요.
- **버전 관리 손쉬움**: URL에 버전을 명시하면 특정 버전의 패키지를 즉시 사용 가능!
- **특정 모듈만 쓰고 싶을 때 편리**: 프로젝트에 모두 설치하지 않아도 필요한 모듈만 간편히 import 가능해요.

---

## 하지만, 이전에 꼭 알아둬야 할 점!

- 아직 실험적이라 예상치 못한 이슈가 발생할 수 있어요.
- 네트워크 상태에 따라 모듈 로딩 속도가 달라지고, 경우에 따라 실패할 수도 있죠.
- 보안 문제 때문에 신뢰할 수 없는 출처는 무조건 피하셔야 합니다.

---

URL Imports는 앞으로의 모듈 관리와 배포 방식을 바꿀 수 있는 흥미로운 기능이에요. 직접 써보면서 맛보기 좋으니, 작은 프로젝트부터 한번 시도해보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

이번에는 Next.js에서 실험적으로 지원하는 URL Imports 기능에 대해 이야기해볼게요. 이 기능을 활용하면, 원격 URL에서 직접 모듈을 불러와 사용할 수 있어요. 아주 신기하죠?

설정 방법부터 간단하게 설명해 드릴게요. `next.config.js` 파일에 다음과 같이 추가해 줍니다.

```js
module.exports = {
  experimental: {
    urlImports: ['https://example.com/assets/', 'https://cdn.skypack.dev'],
  },
}
```

여기서 `urlImports` 배열 안에는 직접 모듈을 불러오고 싶은 URL 주소의 베이스를 적어줘야 해요. 이렇게 설정한 후엔 아래처럼 URL 경로에서 바로 모듈을 import 할 수 있답니다.

```js
import { a, b, c } from 'https://example.com/assets/some/module.js'
```

이게 왜 좋냐고요? 보통은 npm 패키지를 설치하고 관리해야 하는데, 이렇게 하면 별도로 내려받지 않고도 외부 서버에서 최신 모듈을 바로 가져와 사용할 수 있어요. 특히 CDN에 호스팅된 유틸리티나 라이브러리를 가져오는 데 굉장히 편리하죠.

하지만 주의할 점도 있어요.  
- 외부 서버 상태에 따라 앱 로딩 속도나 안정성에 영향을 받을 수 있어요.  
- 보안상 신뢰할 수 있는 URL만 등록하는 게 중요해요.  
- 아직은 실험적인 기능이라 완전한 안정성은 보장되지 않으니 프로덕션에 바로 적용하기 전 충분히 테스트하는 걸 추천합니다.

참고로, 이 URL Imports는 일반적인 npm 패키지 import 할 수 있는 모든 곳에서 사용할 수 있어요. 예를 들어 components, utils 스크립트 안에서도 똑같이 쓸 수 있다는 뜻이에요.

마지막으로, 이 기능이 발전하면 패키지 설치와 관리가 훨씬 간편해질 수도 있으니 앞으로도 계속 관심 가져볼 만한 기능이랍니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 보안 모델(Security Model)

이번 기능은 보안을 최우선으로 생각하며 설계되고 있어요. 우선, URL 임포트를 허용할 도메인을 명시적으로 지정하도록 강제하는 실험적 플래그(flag)를 추가했답니다. 이게 왜 중요하냐면, 내 코드가 외부에서 불러오는 리소스를 무분별하게 받아들이면 보안 취약점이 생길 수 있기 때문이죠. 앞으로는 URL 임포트가 브라우저 샌드박스 환경인 Edge Runtime에서만 실행되도록 범위를 제한해서, 더 안전하게 만들 계획입니다.

사실 이렇게 도메인 허용 리스트를 관리하는 건 좋은 습관이에요. 여러분도 꼭 쓰는 서드파티 라이브러리나 리소스의 출처를 명확히 하고, 필요 없는 외부 URL은 차단하는 걸 잊지 마세요.

## Lockfile

URL 임포트를 사용하면, Next.js는 `next.lock`이라는 디렉터리를 만들어서 그 안에 락파일(lockfile)과 함께 실제로 받아온 자산(asset)들을 저장해요. 중요한 점은, 이 `next.lock` 폴더를 `.gitignore`에 넣고 무시하지 말고 꼭 Git에 커밋해야 한다는 거예요.

왜 그럴까요? 바로 팀원들이나 CI/CD 환경에서 동일한 외부 의존성을 정확히 재현하기 위해서입니다. 만약 이 폴더를 깃에서 제외하면, 다른 개발자들이나 배포 파이프라인에서 같은 자산을 보장할 수 없게 돼서 문제를 일으킬 수 있죠.

---

추가로, 이런 락파일이나 다운로드한 의존성을 커밋하는 방식은 npm의 `package-lock.json`이나 Yarn의 `yarn.lock` 과 비슷한 역할을 해요. 외부 URL을 통한 의존성도 안전하게 관리하려면 이런 락 파일 관리는 필수겠죠? 이번 기회에 lockfile 관리에 신경 쓰시면 좋겠네요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Next.js에서 URL Imports를 다룰 때 중요한 두 가지 동작 방식을 쉽게 설명해볼게요.

- **next dev 실행 시**: Next.js가 새로 발견한 URL Imports들을 모두 다운로드해서 `lockfile`에 추가해줘요.
- **next build 실행 시**: 실제 배포용 빌드를 할 때는 오직 `lockfile`에 기록된 URL Imports 만 사용해요.

한마디로, 개발 모드에서는 네트워크에서 해당 URL들을 받으면서 업데이트하고, 빌드할 때는 안정성을 위해 네트워크 요청 없이 `lockfile`에 있는 내용만 써서 빌드를 해요. 그래서 `lockfile`이 오래되면 빌드가 실패할 수도 있죠. 다만, 딱 한 가지 예외가 있는데요. 만약 URL이 `Cache-Control: no-cache` 헤더로 응답한다면, 이 리소스는 `lockfile`에 `no-cache` 항목으로 기록되고, 빌드할 때마다 네트워크에서 항상 최신 내용을 받아와요.

조금 더 감을 잡으라고 예제를 보여드릴게요.

## 예제

### Skypack

Skypack 같은 CDN에서 패키지를 URL Import로 불러올 때 이 동작 방식이 어떻게 적용되는지 확인할 수 있어요.

---

추가로, 만약 여러분이 Next.js에서 URL Import를 사용한다면 `lockfile` 관리를 꼼꼼히 하는 게 매우 중요하답니다. 이 파일은 프로젝트 루트에 보통 `.next/imports.lock` 형태로 존재하는데, 이걸 잘 확인하고 관리해야 나중에 빌드 에러를 피할 수 있어요.

그리고, 개발 중에 새로운 URL Import를 추가하거나, CDN에서 새로운 버전이 나왔을 때도 `next dev`를 한 번 돌려줘야 `lockfile`이 최신 상태로 유지된답니다. 빌드파이프라인에 넣는다면 캐시 관리 전략도 잘 세우는 것이 좋겠죠?

Markdown으로 표를 만들어 정리하면 아래와 같아요.

| 명령어       | 동작 설명                                            |
|--------------|-----------------------------------------------------|
| `next dev`   | 새로 발견된 URL Import를 다운로드하고 lockfile에 추가 |
| `next build` | lockfile에 기록된 URL Import만 사용해 빌드           |

이정도면 URL Import 관련 작업 흐름을 이해하는 데 도움이 됐길 바라요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

이번에는 React 코드 예제와 함께 이미지 import 방법, 그리고 CSS에서 URL을 사용하는 방법에 대해 살펴볼게요. Next.js나 React 프로젝트에서 이미지를 다룰 때 유용한 팁도 함께 알려드릴게요.

---

## React에서 confetti 효과 넣기

```js
import confetti from 'https://cdn.skypack.dev/canvas-confetti'
import { useEffect } from 'react'
 
export default () => {
  useEffect(() => {
    confetti()
  })
  return <p>Hello</p>
}
```

위 코드는 `canvas-confetti` 라이브러리를 사용해서 페이지가 로드될 때 폭죽 터지는 효과를 내는 예제입니다. `useEffect` 안에 `confetti()`를 호출하면 컴포넌트가 마운트될 때마다 confetti가 실행되죠.

> 참고로, `useEffect` 두 번째 파라미터로 빈 배열 `[]`을 넣으면 마운트 시에만 실행되어 성능상 더 좋습니다.

```js
useEffect(() => {
  confetti()
}, []) // 한 번만 실행
```

---

## 정적 이미지 import하기 (Static Image Imports)

```js
import Image from 'next/image'
import logo from 'https://example.com/assets/logo.png'
 
export default () => (
  <div>
    <Image src={logo} placeholder="blur" />
  </div>
)
```

Next.js에서 이미지 최적화를 위해 `next/image`를 많이 사용하죠? 위처럼 URL로 이미지를 직접 import하는 방법도 있지만, 사실 Next.js가 공식적으로 지원하는 `next/image`의 `src` prop에는 보통 로컬 파일 경로나 공개된 URL 문자열이 들어갑니다.

> 이렇게 `import logo from '...'` 방식은 보통 `next.config.js`에서 remote 패턴이 설정되어 있어야 동작합니다.  
> 그리고 `placeholder="blur"`를 사용하면 로딩 전 저해상도 블러 이미지가 잠깐 보이면서 UX가 향상됩니다.

---

## CSS의 URL 사용법

마지막으로 CSS에서 URL을 사용할 때는 보통 백그라운드 이미지 등으로 이렇게 쓰죠:

```css
.my-div {
  background-image: url('/images/bg.png');
}
```

CSS 파일 내에서 URL을 넣을 때 유의할 점!

- URL 경로가 올바른지 (특히 빌드 시 경로 변환 이슈 체크)
- Next.js같은 프레임워크에서는 public 폴더 하위에 이미지 넣고 `/images/bg.png`처럼 절대경로로 쓰는 게 편리

---

### 정리: 이미지 다룰 때 주의점

| 포인트                 | 설명                                                                    |
|------------------------|-------------------------------------------------------------------------|
| 이미지 import 방식      | 로컬 이미지 import는 `import img from '...'` 로, URL 문자열도 가능       |
| next/image 사용 시      | 최적화, lazy-loading, placeholder(blurry) 기능 활용                      |
| CSS url 경로           | public 폴더 내 이미지 절대경로로 지정하는 게 안전                         |
| confetti 효과 넣기     | `canvas-confetti` 라이브러리로 간단히 폭죽 효과 구현 가능                |

---

다양한 방식으로 이미지를 다루고 효과를 넣는 방법을 알아봤는데요, 프로젝트 상황에 따라 적절한 방법을 선택해서 더 멋진 UI/UX를 만들어 보시길 바랍니다! 궁금한 점 있으면 또 알려주세요 :)


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

JS에서 이미지나 파일 경로를 다룰 때, 그냥 문자열로 쓰는 것과 URL 객체로 처리하는 방식이 있어요. 예제 코드도 두 가지 상황을 보여주는데요, 쉽게 설명해드릴게요.

```css
.className {
  background: url('https://example.com/assets/hero.jpg');
}
```
이 코드는 CSS에서 배경 이미지로 직접 URL을 지정하는 경우예요. 이러면 그냥 해당 링크로 바로 이미지가 로드됩니다. 근데 이런 방식은 빌드나 배포 시 파일이 어떻게 관리되는지에 따라 문제가 생길 수 있어요.

---

```js
const logo = new URL('https://example.com/assets/file.txt', import.meta.url);

console.log(logo.pathname);

// 출력 예시: "/_next/static/media/file.a9727b5d.txt"
```

두 번째 코드는 JavaScript 모듈 안에서 `URL` 객체를 생성해서 파일 경로를 관리하는 예시예요. `import.meta.url`은 현재 모듈의 URL을 알려주고, 이걸 기준으로 상대경로나 절대경로를 처리할 수 있죠.

예를 들어 Next.js나 Vite 같은 최신 프레임워크들은 Assets(이미지, 폰트, 텍스트 파일 등)를 이렇게 import하거나 URL 객체화 해서 다뤄요. 이렇게 하면 빌드 시점에 최적화된 경로(해시가 붙거나 static 경로로 변경된 경로)로 변환되니까, 실제 배포된 파일 위치와 항상 맞게 관리할 수 있어요.

| 장점 | 설명 |
| --- | --- |
| 빌드 최적화 지원 | 파일명에 해시가 붙어 캐시 무효화 자동 처리 가능 |
| 경로 관리 용이 | 상대 패스 문제를 줄이고, 절대 경로 기반으로 안정적으로 자원 참조 |
| 타입 안정성 | 타입스크립트 사용 시, import 시점에 오류 잡기 용이 |

---

### 추가 팁

- CSS에서 URL 경로를 지정할 때, 로컬 파일이라면 웹팩이나 Vite 같은 빌드 도구가 알아서 경로를 처리하게끔 설정하는 게 좋아요.
- JS에서 URL 객체 쓸 때는, URL 생성자가 브라우저 환경과 Node 환경에서 다르게 동작할 수 있으니 환경도 확인하세요.
- Next.js 같은 경우는 `import`로 이미지, 텍스트 파일 등을 직접 불러와서 JSX에 쓸 수 있으니, 공식 문서 참고하는 걸 추천해요.

이렇게 파일 경로나 자원 관리를 조금만 신경 써도 배포 후 깨지는 이미지 문제나 경로 문제를 훨씬 줄일 수 있어요! 개발할 때 자주 보게 될 테니까 익숙해지면 좋습니다 :)

Next.js 15에서 urlImports 기능 활용하는 방법

# trailingSlash 설정하기

Next.js를 사용하다 보면 URL 끝에 슬래시(/)가 붙는 경우와 안 붙는 경우가 있는데요, 기본적으로 Next.js는 슬래시가 붙은 URL을 슬래시가 없는 버전으로 리다이렉트해 줍니다. 예를 들면 `/about/`로 접속하면 `/about`으로 자동 이동하는 식이죠.

근데 가끔은 반대로, 슬래시가 없는 URL을 슬래시가 붙은 URL로 리다이렉트하고 싶을 때가 있어요. 이럴 때, `next.config.js` 파일에서 `trailingSlash` 설정을 바꿔주면 됩니다.

```js
module.exports = {
  trailingSlash: true,  // true로 설정하면 슬래시가 없는 URL은 슬래시가 있는 URL로 리다이렉트됩니다.
}
```

### 추가 팁!
- 이 설정은 SEO에도 중요한 역할을 해요. URL이 일정한 형식을 갖춰야 중복 콘텐츠 문제를 막을 수 있거든요.
- 만약 여러분이 정적 사이트 생성(Static Site Generation)을 하고 있다면, 이 옵션을 사용하면 빌드 시 정적 파일들이 `/about/index.html`처럼 폴더 형태로 생성되기 때문에 호스팅 환경에 따라 좀 더 편리할 수 있습니다.

간단하니까 애플리케이션 특성에 맞게 한 번 적용해 보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

이 옵션을 설정하면 /about 같은 URL이 /about/으로 리다이렉트됩니다.

그런데 trailingSlash: true 옵션을 사용할 때는 예외가 몇 가지 있어요. 그 예외에 해당하는 URL들은 뒤에 슬래시가 붙지 않습니다:

- 확장자가 있는 정적 파일 URL들 (예: .txt, .png, .json 등)
- .well-known/ 경로 하위에 있는 모든 경로들

즉, 아래와 같은 URL들은 변경 없이 그대로 유지됩니다:

| URL                              | 설명               |
|---------------------------------|--------------------|
| /file.txt                       | 텍스트 파일         |
| images/photos/picture.png       | 이미지 파일         |
| .well-known/subfolder/config.json | .well-known 하위 설정 파일 |

추가로 말씀드리자면, 이렇게 슬래시 유무가 중요한 이유는 웹서버나 프레임워크에서 URL을 해석하는 방식 때문인데요, 보통 폴더 경로를 나타낼 때는 뒤에 슬래시를 붙이고, 파일 경로는 붙이지 않아요. 그래서 이런 규칙을 잘 지키면 SEO와 사용자 경험에도 더 좋아집니다.

만약 프로젝트에서 이 옵션을 바꿔야 할 일이 있다면, 변경 후에 URL 리다이렉트 설정도 한 번 꼭 확인해보시는 걸 추천드려요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

output: "export" 설정과 함께 사용하면, /about 페이지가 기본적인 /about.html 대신 /about/index.html로 출력됩니다. 이게 왜 좋냐면, URL 경로가 좀 더 깔끔해지고 폴더 구조와도 맞아떨어져서 SEO나 서버 설정 시에 유용할 수 있어요.

## 버전 히스토리

| 버전      | 변경사항               |
|-----------|-----------------------|
| v9.5.0    | trailingSlash 옵션 추가 | 

이 trailingSlash 옵션은 페이지 경로 끝에 슬래시(/)를 붙일지 말지를 결정하는 옵션이라, 웹사이트 구조를 좀 더 유연하게 관리할 수 있게 해줍니다. 만약 여러분이 정적 사이트 생성기처럼 페이지를 폴더 구조로 관리하고 싶다면 이 옵션을 적극 활용해보세요!

Next.js 15에서 trailingSlash 설정으로 URL 끝 슬래시 처리하는 방법

# transpilePackages

Next.js에서는 로컬 패키지(예: 모노레포 안의 패키지들)나 외부 의존성(node_modules)에 있는 패키지들을 자동으로 트랜스파일(transpile)하고 번들링할 수 있는 기능을 제공합니다. 이 기능 덕분에 예전에는 별도의 라이브러리인 `next-transpile-modules`를 사용해야 했지만, 이제는 Next.js 내장 기능으로 훨씬 간편하게 처리할 수 있게 되었어요.

사용법도 아주 간단합니다. `next.config.js` 파일에 아래처럼 `transpilePackages` 옵션에 트랜스파일하고 싶은 패키지 이름을 배열로 넣기만 하면 됩니다:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['package-name'],
}

module.exports = nextConfig
```

### 왜 이 기능이 필요할까?

일반적으로 Next.js 프로젝트에서 외부 라이브러리를 사용할 때는 이미 컴파일된 상태라서 별도의 트랜스파일 과정이 필요 없는데요. 하지만 모노레포(monorepo)처럼 내 프로젝트 안에 여러 패키지가 공존하거나, 외부 라이브러리 중에 최신 문법(예: ES6 이상 모듈이나 JSX)이 포함되어 있는 경우 바로 사용할 수 없을 때가 있어요. 이럴 때 `transpilePackages`를 이용하면 Next.js가 빌드 시 해당 패키지들을 자동으로 트랜스파일해줘서, 별도의 설정 없이 신경 쓰지 않고도 최신 문법을 사용할 수 있게 해줍니다.

### 참고로 알아두면 좋은 팁

- 여러 패키지를 한꺼번에 트랜스파일하려면 배열에 계속 추가하면 됩니다: `transpilePackages: ['package-a', 'package-b']`
- 모노레포 구조에서 `packages/` 폴더 아래에 있는 라이브러리들을 배포 없이 바로 개발 서버에서 테스트할 때 특히 유용해요.
- Next.js 12 버전 이상에서 공식 지원되니, 최신 버전 사용을 권장합니다.

---

## 버전 히스토리 (Version History)

| 버전 | 변경사항                              |
|-------|------------------------------------|
| 12.x  | `transpilePackages` 기능 최초 도입 |
| 최신  | 외부 라이브러리 트랜스파일 지원 확장 | 

Next.js를 사용하면서 모노레포나 커스텀 패키지 관리가 고민이었다면, 이 기능을 꼭 활용해보세요. 설정 단순하고 성능도 좋으니 작업 효율이 확실히 올라갈 거예요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

아래는 표를 마크다운 형식으로 바꾼 모습이에요. 실제로 개발 관련 문서나 블로그 글 쓸 때 이렇게 마크다운으로 정리해두면 훨씬 깔끔하고 보기 좋답니다!

| Version  | Changes                   |
|----------|---------------------------|
| `v13.0.0` | `transpilePackages` added.|

특히 이번 `v13.0.0` 버전에서는 `transpilePackages`라는 기능이 추가되었는데요, 이건 번들링이나 빌드할 때 특정 패키지를 트랜스파일할 수 있게 해주는 옵션이에요. 예를 들어, 프로젝트에서 일부 외부 패키지가 최신 자바스크립트 문법을 사용해서 브라우저 호환성을 위해 트랜스파일이 필요할 때 유용하죠.

더 자세한 내용이나 사용법 궁금하면 언제든 알려주세요!

Next.js 15에서 transpilePackages 설정으로 패키지 트랜스파일 쉽게 하는 방법

# Turbopack 설정하기

안녕하세요! 오늘은 Next.js에서 **Turbopack** 옵션을 커스터마이징하는 방법에 대해 이야기해볼게요. Turbopack은 파일 변환 방법이나 모듈 해석 방식을 직접 설정할 수 있게 해주는데요, 덕분에 프로젝트에 맞게 빌드 과정을 세밀하게 조절할 수 있어요.

기본적인 설정 예시는 다음과 같아요:

```js
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  turbopack: {
    // 여기서 Turbopack 커스터마이징 옵션들을 설정합니다.
  },
}
 
export default nextConfig
```

### 알아두면 좋은 점!
Turbopack은 Next.js에 기본 내장된 기능들이 많아서 별도의 로더(loader) 설정 없이도 잘 돌아간다는 점이 큰 장점이에요.

- CSS 처리나 최신 자바스크립트 컴파일을 기본적으로 지원해서,
- 따로 `css-loader`, `postcss-loader` 혹은 `babel-loader` 같은 로더를 설치하거나 설정할 필요가 없어요.
- 특히 `@babel/preset-env`를 쓰는 경우라면 추가 설정 없이도 최신 문법을 문제없이 빌드할 수 있다는 뜻이죠.

이게 왜 좋은지 궁금하다면, 보통 Webpack으로 직접 셋업할 때 이 로더들 때문에 설정이 엄청 복잡해질 수 있는데 Turbopack은 그런 번거로움을 줄여준다고 생각하면 돼요.

### 추가로!
Turbopack은 아직 발전 중인 빌드 도구라서, 만약 기존 Webpack 환경에서 옮겨온다면 일부 옵션들은 다르게 동작할 수 있어요. 문서와 커뮤니티를 수시로 체크해서 최신 변경사항을 따라가는 걸 추천합니다!

혹시 Turbopack 설정에 대해 더 궁금한 점이나 도움이 필요하다면 편하게 물어봐 주세요. 함께 공부해봐요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

## 참고 자료

### 옵션들

turbo 설정에서 사용할 수 있는 옵션들은 다음과 같아요:

| 옵션               | 설명                                                                 |
|--------------------|----------------------------------------------------------------------|
| `root`             | 애플리케이션의 루트 디렉토리를 설정해요. 절대 경로여야 합니다.       |
| `rules`            | Turbopack을 사용할 때 적용할 지원되는 webpack 로더들의 리스트입니다. |
| `resolveAlias`     | 별칭으로 된 import들을 실제 로드할 모듈로 매핑해요.                   |
| `resolveExtensions`| 파일을 import할 때 해결할 확장자 리스트를 지정해요.                   |

---

여기서 `root` 옵션은 프로젝트가 어디서부터 시작하는지 알려주는 역할을 해요. 보통 절대 경로를 줘야 하니까, 예를 들어 `/Users/username/projects/my-app` 같은 식으로요.

`rules`는 webpack에서 익숙한 부분인데, Turbopack에서도 비슷하게 특정 파일 유형에 대해 어떤 로더(예: Babel, 스타일 로더 등)를 적용할지 설정하는 거예요.

`resolveAlias`는 자주 쓰이는 경로나 모듈 이름에 별칭을 붙여서 import할 때 좀 더 간편하게 하기 위한 옵션입니다. 예를 들어, `@components`를 `src/components`로 매핑하면 import 구문이 훨씬 깔끔해지죠.

마지막으로 `resolveExtensions`는 파일 확장자를 굳이 다 붙이지 않고도 import할 수 있게 해줍니다. 예를 들어, `index.js`, `index.tsx` 등이 있을 때 `.js`, `.tsx` 등 원하는 확장자를 배열로 넣으면 편리하죠.

이렇게 옵션을 설정해두면 Turbopack을 좀 더 유연하고 효율적으로 사용할 수 있습니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### 지원하는 로더(Loaders)

Turbopack의 webpack 로더 구현과 함께 테스트를 마친 로더들은 다음과 같습니다:

| 로더 이름             | 설명                                  |
|-----------------------|-------------------------------------|
| babel-loader          | 최신 자바스크립트를 구형 브라우저에서도 돌아가게 변환해주는 로더          |
| @svgr/webpack         | SVG 아이콘을 React 컴포넌트로 변환해주는 로더                        |
| svg-inline-loader     | SVG를 인라인으로 불러올 수 있게 해주는 로더                       |
| yaml-loader           | YAML 파일을 자바스크립트 객체로 변환해서 불러올 수 있는 로더          |
| string-replace-loader | 문자열 치환 작업을 빌드 과정에서 처리해주는 로더                      |
| raw-loader            | 파일을 문자열 그대로 불러올 때 사용하는 로더                         |
| sass-loader           | SASS/SCSS 파일을 CSS로 변환해주는 로더                           |

이렇게 자주 쓰이는 로더들은 Turbopack 환경에서도 안정적으로 작동한다는 점, 개발자 입장에서 참 반갑죠? 특히 Babel, SASS 같이 거의 필수적인 로더들이 지원되니까 프론트엔드 개발에 큰 걱정 없이 사용할 수 있습니다.

---

## 예제 코드들 (Examples)

직접 적용해볼 수 있는 예제들도 함께 살펴보시면 이해가 훨씬 쉬워질 거예요. 앞으로 다양한 예제들을 차근차근 소개해드릴 예정이니 기대해주세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### 루트 디렉토리

Turbopack은 모듈을 해석할 때 **루트 디렉토리(root directory)** 를 기준으로 삼아요. 즉, 프로젝트 루트 밖에 있는 파일들은 모듈로 인식하지 않아서 불러오지 못해요.

여기서 중요한 점은, Next.js가 **자동으로 프로젝트의 루트 디렉토리**를 찾아준다는 것입니다. Next.js는 아래와 같은 파일들 중 하나가 있는 위치를 루트 디렉토리로 인식하는 거죠:

| 파일 이름           |
|---------------------|
| pnpm-lock.yaml      |
| package-lock.json   |
| yarn.lock           |
| bun.lock            |
| bun.lockb           |

예를 들어, `package-lock.json`이 있는 폴더가 바로 루트 디렉토리로 설정돼서, 이 위치를 기준으로 모듈 경로나 파일 경로를 해석하게 됩니 다.

---

### 덧붙여서!

- 만약 이 파일들이 없는 상태라면, Next.js가 루트 디렉토리를 제대로 인식하지 못할 수 있으니, 항상 패키지 매니저 별 락 파일 중 하나 정도는 프로젝트에 꼭 넣어두는 게 좋아요.
- 터보팩(Turbopack)은 특히 빠른 빌드 환경을 제공하는 모듈 번들러이기 때문에, 프로젝트 구조가 깔끔하게 정리되어야 원하는 퍼포먼스를 낼 수 있어요.
- 그리고 만약 루트 밖에 있는 파일을 참조해야 한다면, 그 파일을 프로젝트 내부로 옮기거나 심볼릭 링크를 활용하는 방법도 한 번 고려해보세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

프로젝트 구조가 다르거나, 예를 들어 워크스페이스(workspaces)를 사용하지 않는 경우 root 옵션을 수동으로 설정할 수 있어요:

```js
const path = require('path')
module.exports = {
  turbopack: {
    root: path.join(__dirname, '..'),
  },
}
```

이렇게 하면 Turbopack이 프로젝트의 루트 디렉터리를 정확히 인식할 수 있답니다. 프로젝트 구조가 독특할 때 꼭 기억해두세요!

---

### webpack 로더 설정하기

Turbopack은 기본적으로 다양한 기능을 내장하고 있지만, 때로는 webpack 로더 지원이 필요할 때가 있죠. 다행히도 이미 많은 webpack 로더들이 Turbopack과 호환됩니다. 다만, 현재는 약간의 제한 사항들이 있으니 참고가 필요해요.

예를 들어, 최신 웹 기술이나 특정 파일 형태에 대해 완벽하진 않지만 꾸준히 개선되고 있으니 필요에 따라 적절히 사용해보면 좋습니다. 혹시 여러분이 사용하는 로더가 제대로 동작하지 않는다면 공식 문서나 커뮤니티에서 업데이트 상황을 확인해보는 것도 추천해요!

추가로, Turbopack은 성능을 최우선으로 설계되어 있기 때문에 일부 복잡한 webpack 로더들은 완벽하게 지원하지 않을 수 있어요. 그럴 땐 가능하면 Turbopack 전용 플러그인이나 기능을 활용하는 걸 고민해보세요. 미래에는 더 많은 로더와 플러그인이 원활히 지원될 예정이니 기대해도 좋습니다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

webpack 로더 API는 아직 핵심 기능만 구현된 상태예요. 현재는 인기 있는 로더 몇 가지를 지원하지만, 앞으로 더 많은 API를 확장할 계획입니다. 그리고 한 가지 중요한 점! JavaScript 코드를 반환하는 로더만 지원하고 있어서, 스타일시트나 이미지 같은 파일을 변환하는 로더는 아직 사용할 수 없어요.

또한, webpack 로더에 옵션을 전달할 때는 순수한 자바스크립트 기본 자료형(primitive), 객체, 배열만 허용됩니다. 예를 들어 `require()`를 통해 플러그인 모듈을 옵션 값으로 넘기는 건 지원하지 않아요.

로더를 설정하려면 `next.config.js` 파일에 설치한 로더 이름과 옵션을 추가하면 됩니다. 여기서는 파일 확장자별로 어떤 로더들을 적용할지 매핑해 주는 거죠.

아래 예시는 `.svg` 파일을 `@svgr/webpack` 로더를 사용해 React 컴포넌트로 불러올 수 있게 설정한 코드예요.

```js
module.exports = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}
```

즉, 위 설정을 하면 프로젝트에서 `.svg` 파일을 그냥 import해서 JSX 안에서 컴포넌트처럼 쓸 수 있어 정말 편리하죠! 이런 식으로 필요에 따라 다른 로더들도 설정해서 사용할 수 있으니, 앞으로 로더 API가 확장되면 더 다양한 파일 처리도 가능해질 것 같아요.


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

> 참고할 점: Next.js 13.4.4 버전 이전까지는 turbo.rules가 turbo.loaders라는 이름이었고, *.mdx 같은 파일 확장자는 지원하지 않고 .mdx와 같이 특정 확장자만 받았다는 점이에요.

### 별칭(Alias) 해결하기

Turbopack은 모듈 해석 방식을 별칭(alias)을 통해 커스터마이징할 수 있어요. 웹팩(webpack)의 resolve.alias처럼 동작한다고 생각하면 이해하기 쉬워요.

별칭을 설정하려면 next.config.js 파일에서 import 패턴을 원하는 경로로 매핑해주면 됩니다. 예를 들어, 특정 경로를 더 간단하거나 명확한 이름으로 바꿔 불러올 수 있죠.

```js
// next.config.js
module.exports = {
  experimental: {
    turbopack: true,
  },
  turbopack: {
    resolve: {
      alias: {
        '@components': './src/components',
        '@utils': './src/utils',
      },
    },
  },
};
```

이렇게 설정하면 코드 내에서 `@components/Button`처럼 경로를 간단히 쓸 수 있어요. 별칭을 잘 활용하면 경로 관리가 훨씬 편해지고, 프로젝트가 커져도 유지보수가 훨씬 수월해집니다.

> TIP
> 별칭을 설정할 때는 vscode 같은 편집기에서 path alias가 인식되도록 `jsconfig.json`이나 `tsconfig.json`에도 동일한 별칭을 설정해주면 개발 경험이 더 좋아져요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

```js
module.exports = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash', // underscore 패키지를 lodash로 대체
      mocha: { browser: 'mocha/browser-entry.js' }, // 브라우저 환경에서는 mocha를 mocha/browser-entry.js로 대체
    },
  },
}
```

위 설정은 `underscore`를 불러올 때 실제로는 `lodash` 패키지를 쓰도록 바꾸는 거예요. 그러니까, `import underscore from 'underscore'`라고 적어도 내부적으로는 `lodash`가 불러와지는 거죠.

재밌는 점은 Turbopack이 Node.js의 조건부 익스포트(conditional exports)처럼 조건에 따라 별도의 aliasing을 지원한다는 거예요. 현재는 'browser' 조건만 지원하는데, 예를 들어 위 설정에서는 브라우저 환경일 때 `mocha`를 `mocha/browser-entry.js`로 바꿔서 불러오도록 해준 거죠.

---

### 커스텀 확장자 해결하기 (Resolving custom extensions)

Turbopack에서 자주 만나는 문제 중 하나가 커스텀 확장자를 가진 파일을 제대로 인식하지 못하는 경우예요. 예를 들어 `.jsx`나 `.ts` 같은 확장자를 직접 명시하지 않고 import할 때 자동으로 찾아내야 하는 상황이 있죠.

Turbopack에서는 `resolve` 옵션을 통해 확장자 우선순위를 지정할 수 있어요. 예를 들어 아래처럼 쓸 수 있습니다:

```js
module.exports = {
  turbopack: {
    resolve: {
      extensions: ['.tsx', '.ts', '.jsx', '.js'],
    },
  },
}
```

이렇게 하면 파일을 import할 때 확장자를 생략해도 Turbopack이 순서대로 확장자를 붙여가며 찾아줍니다. 예를 들어 `import Component from './MyComponent'` 할 때 `MyComponent.tsx`, `MyComponent.ts` 등을 찾는 식이죠.

---

추가 팁!  
요즘 프로젝트에서는 다양한 파일 확장자를 다루다 보니, alias와 resolve 설정을 잘 조합하는 게 생산성을 크게 높여줘요. 특히, 라이브러리 교체(aliasing)와 타입스크립트+JSX 지원(resolve extensions)을 같이 하면 깔끔하고 빠른 빌드 환경을 만들 수 있답니다.

궁금한 점 있으면 언제든 물어봐 주세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Turbopack에서도 webpack의 resolve.extensions 설정처럼 모듈을 불러올 때 사용하는 파일 확장자를 커스텀할 수 있어요.

설정을 바꾸려면 next.config.js 파일에 `resolveExtensions` 필드를 추가해주면 됩니다. 예를 들어:

```js
module.exports = {
  turbopack: {
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
  },
}
```

위처럼 설정하면 기본 확장자 목록이 해당 리스트로 완전히 바뀌니까, 기존에 자주 쓰던 확장자들(`.js`, `.json` 등)을 꼭 포함시켜야 해요. 안 그러면 의도치 않게 모듈이 제대로 해석되지 않을 수 있거든요.

추가로, 이런 설정들은 주로 TypeScript, MDX 같은 파일들을 함께 사용할 때 유용해요. 예를 들어 TSX 파일도 같이 처리하거나, 마크다운 확장자인 MDX를 빌드에 포함시키고 싶을 때 말이죠.

참고로, 확장자 순서도 중요할 수 있는데, Turbopack이 왼쪽부터 차례대로 확장자를 탐색해서 가장 먼저 매치되는 모듈을 사용하니까, 자주 쓰거나 우선순위가 높은 확장자를 앞쪽에 배치하는 게 좋아요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

더 자세한 내용과 Webpack에서 Turbopack으로 앱을 마이그레이션하는 방법에 대한 가이드는 Turbopack의 Webpack 호환성 문서를 참고하세요.

## 버전 히스토리

| 버전       | 변경사항                          |
|------------|---------------------------------|
| 15.3.0     | `experimental.turbo`가 `turbopack`으로 변경됨.  |
| 13.0.0     | `experimental.turbo` 기능 도입됨.               |

여기서 한 가지 팁! Turbopack은 Next.js 팀에서 개발한 매우 빠른 번들러인데요, 기존 Webpack보다 훨씬 빌드 속도와 HMR(Hot Module Replacement) 성능이 뛰어나서 점점 더 대세로 떠오르고 있어요. 물론 아직 실험적인 기능이 많으니, 프로젝트에 바로 적용하는 것보단 충분히 테스트해보는 걸 추천합니다!

Next.js 15 Turbopack 번들러 사용법

# staticGeneration*

Next.js의 staticGeneration* 옵션은 정적 생성(Static Generation) 과정에서 조금 더 세밀하게 설정하고 싶을 때 사용해요. 특히 프로젝트가 커지거나 빌드 환경이 복잡할 때 도움 되죠.

아래는 간단한 예시 코드입니다:

```js
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    staticGenerationRetryCount: 1,
    staticGenerationMaxConcurrency: 8,
    staticGenerationMinPagesPerWorker: 25,
  },
}

export default nextConfig
```

이 옵션들은 `experimental` 아래에 넣어야 하는데, 아직 실험 단계임을 기억해 주세요.

## Config Options

| 옵션 이름                      | 설명                                                                                     | 기본값        |
|-----------------------------|----------------------------------------------------------------------------------------|------------|
| `staticGenerationRetryCount` | 정적 생성 중 실패한 페이지에 대해 재시도하는 횟수를 설정합니다. (예: 네트워크 문제 등)                  | 0          |
| `staticGenerationMaxConcurrency` | 정적 생성 작업을 동시에 처리할 최대 작업 수를 결정합니다. 빌드 시간이 중요할 때 조절해 성능 최적화 가능. | CPU 코어 수 기준 기본값 |
| `staticGenerationMinPagesPerWorker` | 각 워커(프로세스)에 할당되는 최소 페이지 수를 설정해서 과도한 스레드 분할을 막습니다.                 | 10         |

### 좀 더 부연 설명하면…

- `staticGenerationRetryCount`는 네트워크 문제나 외부 API 호출 실패 등으로 인해 생성이 실패한 페이지를 몇 번 더 시도할지 정하는 옵션이에요. 실패하는 페이지가 많거나, 간헐적으로 외부 서비스가 불안정할 경우 여길 올려보면 좋아요.

- `staticGenerationMaxConcurrency`는 동시에 실행하는 페이지 생성 수를 조절합니다. 너무 큰 값으로 설정하면 CPU나 메모리 리소스 과다 사용이 우려되고, 너무 작으면 빌드 속도가 느려지니 적당히 조절해야 해요.

- `staticGenerationMinPagesPerWorker`는 워커 단위로 할당하는 페이지 수를 최소치로 지정해 불필요한 워커 쓰레드 생성으로 인해 리소스를 낭비하지 않도록 도와줍니다.

---

Next.js가 엄청난 속도로 발전하는 만큼 이런 실험적 옵션도 계속 업데이트되고 있어요. 프로젝트 상황에 맞게 다양한 설정을 시도해보고, 공식 문서나 커뮤니티 동향도 꾸준히 체크하는 걸 추천합니다! 

만약 빌드 시간이 너무 길어 고민이라면, 이런 옵션으로 병렬 처리와 리소스 사용 방식에 변화를 주는 것이 첫걸음일 수 있어요. 정적 사이트로 사용자에게 빠른 경험을 제공하려면, 빌드 과정 최적화가 굉장히 중요하거든요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

이번에는 페이지를 정적으로 생성할 때 유용하게 쓸 수 있는 설정 옵션들을 한 번 정리해볼게요. 개발할 때 빌드 성능이나 안정성을 높이고 싶을 때 이런 옵션들이 도움이 되니까 잘 참고해봐요!

| 옵션 이름                      | 설명                                             |
|------------------------------|------------------------------------------------|
| staticGenerationRetryCount    | 페이지 생성 실패 시 빌드가 실패하기 전에 재시도하는 횟수 |
| staticGenerationMaxConcurrency | 각 워커(worker)가 동시에 처리할 수 있는 최대 페이지 수   |
| staticGenerationMinPagesPerWorker | 새 워커를 시작하기 전에 최소로 처리해야 하는 페이지 수    |

간단하게 말하면, **staticGenerationRetryCount**는 페이지를 만들다가 실패했을 때 몇 번 더 시도할지를 정해줘요. 예를 들어 네트워크 문제나 외부 API가 잠시 오류가 났을 때 유용하겠죠?

그리고 **staticGenerationMaxConcurrency**는 한 워커가 얼마나 많은 페이지를 동시에 처리할지를 조절해요. 값이 너무 크면 워커가 과부하 될 수 있고, 너무 작으면 빌드가 느려질 수 있으니 적절히 조절하는 게 중요해요.

마지막으로 **staticGenerationMinPagesPerWorker**는 새로운 워커를 시작할 때 최소할당 페이지 수를 정해줍니다. 한마디로 워커를 너무 자주 생성하는 걸 막아서 자원 낭비를 줄이는 역할을 하죠.

이 옵션들을 잘 활용하면 빌드 안정성과 속도 면에서 꽤 큰 도움을 받을 수 있으니, 프로젝트 상황에 맞게 조절해 보시길 추천드려요!

Next.js 15 정적 생성(staticGeneration) 사용 방법

# staleTimes란?

staleTimes는 약간 실험적인 기능인데요, 클라이언트 사이드 라우터 캐시에서 페이지 세그먼트(segment)들을 캐싱할 수 있게 해줍니다. 쉽게 말해, 페이지를 다시 요청하지 않고도 미리 저장된 데이터를 활용하면서도, 일정 시간이 지나면 새로 데이터를 검증하도록 설정할 수 있다는 거죠.

이 기능을 쓰고 싶다면 Next.js 설정 파일(next.config.js)에서 `experimental` 옵션 안에 `staleTimes`를 이렇게 설정해주면 됩니다:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30, // 동적 데이터는 30초마다 재검증
      static: 180, // 정적 데이터는 180초(3분)마다 재검증
    },
  },
}

module.exports = nextConfig
```

즉, 위 설정대로면 **동적 데이터는 30초**, **정적 데이터는 3분** 간 캐시에 보관됐다가 그 이후엔 데이터를 새로 검증합니다.

---

## 좀 더 쉽게 풀어볼게요

- **동적(dynamic)** 데이터는 자주 변할 가능성이 크니까, 캐시 유효기간을 짧게.
- **정적(static)** 데이터는 자주 변하지 않으니, 캐시 유효기간을 길게 잡는 거죠.

이걸 적절히 조절하면, 사용자 입장에서는 페이지가 훨씬 빠르게 로드되면서도, 너무 오래된 데이터가 보여지는 걸 방지할 수 있습니다.

---

## 왜 이 기능이 필요할까?

보통 Next.js에서 데이터 패칭(fetch) 후 렌더링할 때, 매번 서버에 새로 요청하면 속도가 느려지거나 서버 부담이 커질 수 있어요. 여기에 staleTimes를 활용하면, 어느 정도 기간 동안은 캐시된 내용을 쓸 수 있으니 성능 최적화에 크게 도움이 됩니다.

---

## 참고로!

- 아직 experimental 단계라서 Next.js 버전에 따라 동작 방식이 바뀔 수도 있고, 완전 안정적이지 않을 수도 있어요.
- 실제 프로젝트에서 도입할 땐, 충분히 테스트해서 데이터 신선도와 퍼포먼스 사이 균형을 잘 맞춰보세요.

staleTimes를 적용해서 캐시 전략을 잘 세워보면, 사용자 경험 향상에 큰 도움이 될 거예요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

링크 프리페칭(prefetching)에 따라 정적(static)과 동적(dynamic) 속성이 시간 단위(초)로 어떻게 적용되는지 알아볼게요.

| 속성       | 설명                                                                                              | 기본값                |
|------------|-------------------------------------------------------------------------------------------------|-----------------------|
| 동적 (dynamic)  | 페이지가 정적으로 생성되지 않았거나, 완전히 프리페치 되지 않은 경우 사용돼요. 예를 들어 `prefetch='true'`가 아닐 때요.      | 0초 (캐시 안 함)        |
| 정적 (static)   | 정적으로 생성된 페이지거나, Link 컴포넌트의 `prefetch` 속성이 `true`일 때, 또는 `router.prefetch`를 호출할 때 사용해요.  | 5분 (300초)             |

### 한마디 더!
- **로딩 경계(loading boundaries)는 설정된 정적 기간 동안 재사용 가능**하답니다.  
- 부분 렌더링에 영향을 미치지 않아요. 즉, 공유 레이아웃(shared layouts)은 네비게이션할 때마다 자동 재페칭되지 않고, 변경된 페이지만 다시 불러옵니다.  
- 백/포워드 캐시 동작에는 영향을 주지 않아서 레이아웃 변경이나 브라우저 스크롤 위치 유지에도 문제없어요!

이해를 돕기 위해 쉽게 말하자면, 정적 속성은 이미 예측해서 안전하다고 판단한 페이지를 일정 시간 동안 캐시에 저장해두는 것이고, 동적 속성은 그런 캐싱 없이 매번 새로 불러오는 방식이에요.

React 기반의 라우터나 Next.js 같은 프레임워크에서 클라이언트 사이드 라우팅 성능 최적화를 할 때 이런 프리페칭 설정이 굉장히 중요합니다. 캐시 기간을 어떻게 조절하느냐에 따라 유저 경험과 페이지 로딩 속도에 큰 차이가 나기 때문이죠.

추가로, Client Router Cache에 대해 더 자세히 알고 싶다면 공식 문서를 참고하는 걸 추천해요! 해당 기능이 어떻게 작동하고 구성 요소들이 어떻게 상호작용하는지 이해하는 데 큰 도움이 될 거예요.


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

### 버전 히스토리

| Version  | Changes                                  |
| -------- | ---------------------------------------- |
| v15.0.0  | `dynamic`한 `staleTimes` 기본값이 30초에서 0초로 변경됨 |
| v14.2.0  | 실험 중인 `staleTimes` 기능이 도입됨               |

---

여기서 `staleTimes`라는 건 데이터를 캐싱할 때 얼마나 오래 신선하다고 판단할지를 정하는 시간이에요. v14.2.0 버전부터 실험적으로 적용되었고, v15.0.0에서는 기본값이 30초에서 0초로 바뀌어서 캐시된 데이터가 바로 오래된 것으로 간주된다는 의미랍니다.

이 기능이 바뀌면서 데이터의 최신성을 더 중요하게 생각하는 환경에서는 유용할 수 있어요. 물론, 너무 짧으면 매번 데이터를 새로 받아오게 돼서 네트워크 비용이 늘어나니 상황에 맞게 잘 조절하는 게 필요해요. 나중에 이 부분을 직접 조정해보면서 최적화하는 것도 꽤 재밌는 작업이 될 거예요!

Nextjs에서 캐싱된 데이터 업데이트 하는 방법(staleTime)

# serverExternalPackages

Next.js 13부터 Server Components와 Route Handlers 내부에서 사용하는 의존성들은 기본적으로 Next.js가 자동으로 번들링해줘요. 덕분에 서버에서 필요한 패키지를 따로 신경 쓸 필요가 줄어들죠.

그런데 만약 어떤 의존성이 Node.js의 특정 기능들(예: 파일 시스템 접근, 네이티브 모듈 등)을 사용하고 있어서, Next.js가 번들링하는 과정에서 문제가 생긴다면? 이때는 serverExternalPackages라는 옵션을 활용할 수 있어요. 이 옵션에 해당 패키지를 적으면 Next.js가 그 패키지를 번들링하지 않고, 대신 Node.js의 `require()`를 이용해 네이티브 방식으로 불러오게 됩니다.

예를 들어, '@acme/ui'라는 패키지를 이렇게 설정할 수 있어요.

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ['@acme/ui'],
}
 
module.exports = nextConfig
```

이 설정은 '@acme/ui'를 서버 번들링에서 제외하고, Node.js 환경에서 직접 불러오도록 지시하는 거예요.

---

### 추가 팁!

- 대부분의 패키지는 굳이 이 옵션에 넣지 않아도 잘 작동해요. 서버 번들링이 문제를 일으키는 경우에만 선별적으로 사용하세요.
- `serverExternalPackages`에 너무 많은 패키지를 넣으면 오히려 빌드 성능에 영향을 줄 수 있으니 꼭 필요한 것만 넣는 게 좋아요.
- 이 기능은 주로 네이티브 모듈이나, 빌드 타임에 처리하기 어려운 Node.js 환경 전용 라이브러리에서 유용합니다.

서버 컴포넌트와 라우트 핸들러를 활용할 때, 이런 설정 하나만으로도 라이브러리 호환성을 좀 더 쉽게 맞출 수 있으니 참고하세요!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Next.js에서 현재 호환성을 작업 중이고 자동으로 제외 처리되는 인기 패키지 리스트가 있어요. 이 리스트에 포함된 패키지들은 Next.js 환경에서 문제없이 사용할 수 있도록 특별히 관리되고 있답니다.

아래는 그 인기 패키지 리스트예요:

- @appsignal/nodejs
- @aws-sdk/client-s3
- @aws-sdk/s3-presigned-post
- @blockfrost/blockfrost-js
- @highlight-run/node
- @huggingface/transformers
- @jpg-store/lucid-cardano
- @libsql/client
- @mikro-orm/core
- @mikro-orm/knex
- @node-rs/argon2
- @node-rs/bcrypt
- @prisma/client
- @react-pdf/renderer
- @sentry/profiling-node
- @sparticuz/chromium
- @swc/core
- @xenova/transformers
- argon2
- autoprefixer
- aws-crt
- bcrypt
- better-sqlite3
- canvas
- chromadb-default-embed
- cpu-features
- cypress
- dd-trace
- eslint
- express
- firebase-admin
- import-in-the-middle
- isolated-vm
- jest
- jsdom
- keyv
- libsql
- mdx-bundler
- mongodb
- mongoose
- newrelic
- next-mdx-remote
- next-seo
- node-cron
- node-pty
- node-web-audio-api
- onnxruntime-node
- oslo
- pg
- playwright
- playwright-core
- postcss
- prettier
- prisma
- puppeteer-core
- puppeteer
- require-in-the-middle
- rimraf
- sharp
- shiki
- sqlite3
- ts-node
- ts-morph
- typescript
- vscode-oniguruma
- webpack
- websocket
- zeromq

이런 패키지들은 Next.js가 서버 컴포넌트에서 처리할 때 자동으로 제외 처리되어 호환성이나 빌드 오류 걱정을 줄여줍니다. 즉, 앞으로 직접 호환성을 설정하는 대신 이 리스트에 포함되어 있으면 알아서 잘 작동할 거라는 뜻이죠.

그리고 빼놓으면 안 될 업데이트 소식! 

| 버전      | 변경 사항                                                                            |
|-----------|-------------------------------------------------------------------------------------|
| v15.0.0   | 기능이 experimental 단계에서 안정화(stable) 단계로 변경되었어요.  그리고 설정 이름이 `<code>serverComponentsExternalPackages</code>`에서 `<code>serverExternalPackages</code>`로 바뀌었답니다. |

이 부분은 Next.js가 서버 컴포넌트 관련 설정을 좀더 명확하게 정리한 거예요. 만약 기존에 experimental 옵션을 써서 외부 패키지를 관리하고 있었다면, 이 점을 참고해서 설정을 고쳐야 해요.

---

추가로 조금 더 알려드리자면, Next.js는 점점 서버 컴포넌트(Server Components) 지원을 강화하면서 다양한 외부 패키지와의 호환성을 신경 쓰고 있어요. 서버 컴포넌트는 클라이언트에 전달하지 않고 서버에서 렌더링하는 컴포넌트로, 서버-클라이언트 경계를 나누는 데 혁신적인 역할을 하고 있죠.

하지만 서버 컴포넌트에서는 모든 패키지가 안전하게 동작하지 않을 수 있어서, 지금처럼 '자동 opt-out' 리스트를 만들어 관리하는 거랍니다. 앞으로 여기에 올라오는 패키지가 점점 많아질 거라서 개발자 입장에서 점점 더 편리해지겠죠?

필요하다면 이 리스트를 참고해서 내 프로젝트에서 사용하는 패키지가 지원되는지 꼭 확인해 보세요! 그렇게 하면 Next.js 최신 기능들을 더 안정적으로 쓸 수 있어요 :)

Next.js 15에서 서버 외부 패키지 관리하는 방법(serverExternalPackages)

# serverActions

Next.js에서 Server Actions(서버 액션)의 동작 방식을 설정할 수 있는 옵션들에 대해 이야기해볼게요.

## allowedOrigins

서버 액션이 호출될 수 있는 안전한 출처(origin) 도메인을 추가로 설정할 수 있는 옵션입니다. 이게 왜 필요하냐면, 서버 액션 요청이 들어올 때 그 요청의 출처(origin)를 호스트 도메인과 비교해서 일치하는지 확인해요. 이렇게 해서 CSRF(사이트 간 요청 위조) 공격을 막을 수 있죠.

만약 이 옵션을 설정하지 않으면 기본적으로 ‘같은 출처’(same-origin)에서만 서버 액션이 허용됩니다. 즉, 내 도메인에서만 서버 액션을 호출할 수 있어요.

**추가로 알아두면 좋은 점!**  
- allowedOrigins를 적절히 설정하지 않으면, 의도한 외부 도메인에서 서버 액션을 호출하지 못할 수 있어요.  
- 하지만 너무 많은 도메인을 허용하면 보안상 위험이 커질 수 있으니 꼭 필요한 도메인만 추가하는 게 좋아요.

아래는 allowedOrigins 옵션을 설정하는 예시입니다.

```js
export const serverActions = {
  allowedOrigins: ['https://mytrusted.com', 'https://another-trusted-site.com'],
};
```

이렇게 하면 `mytrusted.com`, `another-trusted-site.com`에서 오는 요청도 서버 액션을 실행할 수 있게 되겠죠!

---

Next.js의 Server Actions는 점점 더 중요해지고 있으니, 이런 보안 설정 하나하나 신경 써서 안전한 서비스를 만들어 봅시다!


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

```js
/** @type {import('next').NextConfig} */
 
module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
      bodySizeLimit: '3mb', // 예시로 3MB로 제한 설정
    },
  },
}
```

---

## bodySizeLimit 옵션 알아보기

Next.js에서 Server Actions(서버 액션)을 사용할 때, 기본적으로 한 번에 보낼 수 있는 요청 바디(request body)의 최대 크기가 1MB로 제한되어 있어요. 이 제한은 서버 리소스가 과도하게 사용되는 걸 막고, 때로는 DDoS 공격 같은 악의적인 대량 요청으로부터 보호하기 위한 거랍니다.

근데 가끔 데이터 양이 많아 1MB 제한을 넘겨야 할 때가 있잖아요? 예를 들어 이미지 같이 비교적 큰 파일을 보내거나, 여러 데이터를 한 번에 전송해야 할 때 말이죠. 이럴 때는 `serverActions.bodySizeLimit` 옵션을 통해 이 제한을 조정할 수 있어요.

### 설정 방법

- 바이트 단위 숫자 (예: 1000)
- 문자열로 크기 표현 (예: `500kb`, `3mb` 등) — `bytes`라는 패키지가 지원하는 형식이에요.

```js
module.exports = {
  experimental: {
    serverActions: {
      bodySizeLimit: '5mb', // 최대 5MB까지 허용
    },
  },
}
```

이렇게 설정하면, 5MB까지 데이터 전송이 가능해져서 보다 큰 요청도 서버 액션에서 처리할 수 있어요.

### 주의할 점

무턱대고 크기 제한을 늘리는 건 피하는 게 좋아요. 너무 크게 하면 서버가 무거워지고, 악성 의도한 대용량 요청에 취약해 질 수 있거든요. 꼭 필요한 경우에만 적절히 조절하고, 필요한 경우 요청을 여러 번에 나눠서 보내는 방법도 고려해 보세요.

---

서버 요청 크기 제한에 관해 종종 헷갈릴 수 있는데, 이렇게 설정해 두면 서버 액션이 좀 더 유연하게 데이터를 처리할 수 있어서 편리하답니다! 다음에는 이런 experimental 옵션 외에, 프로덕션 환경에서 안전성과 성능을 지키는 팁도 알려드릴게요~


<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-4877378276818686"
     data-ad-slot="1549334788"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

Next.js에서 Server Actions 설정하는 방법을 알려드릴게요!

---

### Server Actions 설정 (Next.js 13 버전 기준)

최근 Next.js 14부터 Server Actions가 정식 기능으로 기본 활성화 되어 있는데요, 아직 13 버전을 사용 중이라면 직접 설정을 해줘야 합니다.

예를 들어, `next.config.js` 파일에 아래처럼 `experimental.serverActions` 옵션을 `true`로 설정해주시면 돼요.

```js
/** @type {import('next').NextConfig} */
const config = {
  experimental: {
    serverActions: true,
  },
}

module.exports = config
```

이 설정을 한 후에는 Server Actions를 사용할 수 있습니다.

---

### 참고: Next.js 14 이상에서는?

Next.js 14부터는 Server Actions가 기본적으로 활성화 되어 별도의 설정이 필요 없답니다. 만약 기본 바디 사이즈 제한을 변경하고 싶다면 아래처럼 설정할 수 있어요.

```js
/** @type {import('next').NextConfig} */

module.exports = {
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb',
    },
  },
}
```

이렇게 하면 서버 액션의 요청 바디 크기 제한을 조절할 수 있습니다.

---

### 제가 추가로 알려드릴 팁!

- **Server Actions 란?**

  서버 액션은 클라이언트에서 서버 함수 호출을 훨씬 쉽게 만들어주는 Next.js의 강력한 기능입니다.

- **bodySizeLimit 설정이 중요한 이유**

  서버에 보내는 데이터 양이 많아지면 기본 제한 때문에 오류가 발생할 수 있어요. 따라서 요청 크기에 따라 적절히 조절해 주는 게 좋아요.

- **Next.js 버전 꼭 확인하기**

  프로젝트 버전에 따라 설정 방법이 다르니, `package.json`에서 Next.js 버전을 꼭 확인하시고 알맞게 설정하세요.

---

필요한 설정을 빠르게 찾는 데 도움이 되었으면 좋겠습니다! Next.js Server Actions, 꼭 직접 사용해보시고 개발 효율을 올려보세요 :)

Posts