# use server

'use server' 지시어는 특정 함수나 파일이 서버 측에서 실행되어야 함을 명시하는 역할을 해요. 파일 맨 위에 쓰면 그 파일 안의 모든 함수가 서버에서 실행된다는 뜻이고, 함수 바로 위에 inline으로 쓰면 그 함수만 서버 함수(Server Function)로 지정할 수 있답니다. 이건 React에서 제공하는 기능이에요.

## 파일 맨 위에 use server 쓰기

아래 예시는 파일 최상단에 `use server` 지시어를 넣은 경우에요. 이렇게 하면 그 안에 있는 모든 함수는 서버에서 실행됩니다.

```js
'use server';

export async function getServerData() {
  // 서버에서만 실행되는 로직
  const data = await fetch('https://api.example.com/data');
  return data.json();
}

export function helperFunction() {
  // 이 함수도 서버에서 실행돼요
}
```

### 추가 설명!

- `use server`를 쓰는 이유는 클라이언트에서 실행하면 안 되는 무거운 연산, 비밀 정보 처리, 데이터베이스 쿼리 등을 서버 쪽으로 감추기 위함이에요.
- React 컴포넌트 내에서 서버 함수 호출 시 클라이언트 코드와 서버 코드를 깔끔하게 분리할 수 있어서 보안과 성능 면에서 유리합니다.
- 만약 한 파일에 서버 함수와 클라이언트 함수가 혼재되어 있으면, 필요한 함수에만 inline으로 `use server`를 붙여서 관리하는 걸 추천해요.

서버 함수 잘 활용하면 앱 구조를 더 명확하게 하고, 유지보수도 쉬워지니 꼭 익혀두시면 좋아요!


<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
// actions.ts
"use server"

import { db } from '@/lib/db'

export async function fetchUsers() {
  const users = await db.user.findMany()
  return users
}
```

이렇게 Server Functions는 `"use server"` 지시어를 파일 상단에 작성해줘야 해요. 그리고 만들고 나면 클라이언트 컴포넌트나 서버 컴포넌트 어디에서든 가져다 쓸 수 있게 됩니다.

예를 들어 클라이언트 컴포넌트에서 fetchUsers 함수를 사용하고 싶으면 이렇게 하면 돼요:

```tsx
"use client"

import { fetchUsers } from './actions'

export default function UserList() {
  async function loadUsers() {
    const users = await fetchUsers()
    console.log(users)
  }

  return <button onClick={() => loadUsers()}>Load Users</button>
}
```

여기서 포인트는 바로 클라이언트 컴포넌트에선 서버 함수가 비동기(Async) 함수라는 점이에요. 이걸 직접 호출하려면 이렇게 버튼 클릭 같은 이벤트 핸들러 안에서 호출하고 결과를 받아서 화면에 보여 주거나 로그를 찍는 식으로 사용합니다.

---

### Server Functions와 Database 연동 정리

| 설명              | 내용                                                         |
|-----------------|------------------------------------------------------------|
| Server Function 생성법    | `use server` 지시어를 파일 상단에 넣고 비동기 함수 작성                |
| Server 함수 위치          | 별도 파일(actions.ts 등)에 작성해 여러 컴포넌트에서 import 가능          |
| Client 컴포넌트에서 사용법 | async 함수 안에서 호출, 이벤트 핸들러에서 호출하는 식으로 비동기 처리        |
| 데이터베이스 연동          | 서버 함수 내에서 직접 `db` 클라이언트를 사용해 데이터 조회/수정 가능         |

---

### 참고 사항
- 아직 Next.js나 React에서 완전히 SSR과 Client 컴포넌트 경계가 명확하여 이 방식을 적용할 때 내가 직접 어떤 작업이 서버에서 일어나고 있는지 분명히 이해하고 사용해야 해요.
- 클라이언트에서 서버 함수를 호출할 때는 내부적으로 서버로 요청이 나가게 된다 생각하면 편해요. 그래서 고통 없는 데이터를 직접 다루는 것보다 네트워크 요청 비용이 있으니 꼭 필요한 경우에만 사용하세요.
- 또, 인증 처리 같은 민감한 로직은 항상 서버 함수에서 관리하는 게 안전합니다.

이 정도 핵심만 잘 이해해 두면 Server Functions를 효과적으로 쓸 수 있어요! 도움이 되었길 바랄게요 :)


<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 Functions를 사용해서 데이터베이스에서 유저 데이터를 가져오는 예제를 살펴볼게요. 그리고 Fetch Users 함수를 클라이언트 컴포넌트에서 어떻게 호출할 수 있는지도 함께 알아봅니다.

---

### 1. Server Function 작성하기

아래 코드는 `fetchUsers`라는 Server Function입니다. 데이터베이스에서 모든 유저를 가져와서 반환해주죠.

```js
import { db } from '@/lib/db' // 데이터베이스 클라이언트 임포트

export async function fetchUsers() {
  const users = await db.user.findMany()
  return users
}
```

여기서 `db.user.findMany()`는 Prisma 같은 ORM을 사용한다고 가정하고, 유저들을 모두 조회하는 코드입니다.

---

### 2. 클라이언트 컴포넌트에서 Server Function 호출하기

이제 위에서 만든 `fetchUsers` 함수를 클라이언트 컴포넌트에서 호출해 보겠습니다.

```js
export default function MyButton() {
  return <button onClick={() => fetchUsers()}>Fetch Users</button>
}
```

버튼 클릭 시 `fetchUsers`가 실행됩니다.

---

### 참고

- 일반적으로 Server Function은 서버에서 실행하기 때문에, 클라이언트에서 직접 호출하려면 Next.js가 지원하는 방식으로 호출해야 합니다.
- 만약 바로 클라이언트에서 `fetchUsers`를 호출하면, 서버 측 환경 변수가 없거나 보안 이슈가 생길 수 있으니 주의하세요.
- Next.js 13 최신 기능 중 하나인 **Inline use server** 문법을 활용하면, 클라이언트 컴포넌트 안에서 서버 함수를 좀 더 쉽게 호출할 수 있습니다.

---

## Using `use server` inline

`use server`는 Server Action 혹은 Server Function을 클라이언트 컴포넌트 내에서 바로 선언하고 사용할 수 있는 문법입니다. 예를 들어,

```js
'use client'

import { useState } from 'react'

export default function MyButton() {
  async function fetchUsers() {
    'use server'  // 여기서 서버 함수 선언
    const users = await db.user.findMany()
    return users
  }

  return <button onClick={() => fetchUsers()}>Fetch Users</button>
}
```

이런 식으로 하면, `fetchUsers` 함수가 서버에서 실행되고 클라이언트에서 호출할 수 있습니다.

---

## 정리

| 개념                | 설명                                                         |
|---------------------|--------------------------------------------------------------|
| Server Function     | 서버에서만 실행되는 함수. 서버 자원에 직접 접근 가능          |
| 클라이언트에서 호출 | 클라이언트에서 호출 시 서버와 통신하거나, Next.js 방식 활용 필요 |
| `use server` inline | 클라이언트 컴포넌트 내에서 서버 함수를 선언하고 실행 가능     |

---

이제 여러분도 Next.js에서 Server Functions를 어떻게 만들고 클라이언트에서 호출하는지 감이 좀 오시죠? 요즘 프레임워크가 점점 더 편리해지고 있어서, 서버와 클라이언트 코드 구분이 한결 수월해지고 있어요. 필요할 때 서버 함수를 잘 활용하면 더 깔끔하고 안전한 앱을 만들 수 있답니다!


<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>

서버 함수(Server Function)를 표시할 때 `use server`를 함수 맨 위에 인라인으로 작성하는 방법에 대해 이야기해볼게요. 아래 예제를 보면, 데이터베이스에서 사용자 목록을 가져오는 함수가 있어요.

```js
import { db } from '@/lib/db' // 데이터베이스 클라이언트 불러오기

export default function UserList() {
  async function fetchUsers() {
    const users = await db.user.findMany()
    return users
  }

  return <button onClick={() => fetchUsers()}>Fetch Users</button>
}
```

이 예제에서는 `fetchUsers` 함수가 서버에서 실행되어야 하는데, 실제로 현재 함수 위에 `use server` 지시어가 빠져 있어요. 이걸 명시하면 Next.js 같은 프레임워크가 이 함수가 서버 전용임을 확실히 알 수 있답니다.

### 서버 함수에 `use server`를 추가할 때는 이렇게!

```js
import { db } from '@/lib/db' // 데이터베이스 클라이언트 불러오기

export default function UserList() {
  "use server"
  
  async function fetchUsers() {
    const users = await db.user.findMany()
    return users
  }

  return <button onClick={() => fetchUsers()}>Fetch Users</button>
}
```

혹은 함수 바로 앞에 붙이는 경우도 있어요.

```js
import { db } from '@/lib/db' // 데이터베이스 클라이언트 불러오기

export default function UserList() {
  const fetchUsers = async () => {
    "use server"
    const users = await db.user.findMany()
    return users
  }

  return <button onClick={() => fetchUsers()}>Fetch Users</button>
}
```

서버 함수는 클라이언트에 번들되지 않고, 서버에서만 실행되도록 보장해줘서 보안 측면에서 매우 중요해요.

---

## 보안 고려사항 (Security considerations)

`use server` 지시어를 사용해 서버 함수를 작성할 때는 보안을 꼭 염두에 두어야 해요. 서버에서 실행되는 만큼, 다음 사항들을 기억하세요:

| 체크포인트                    | 설명                                                                    |
|-----------------------------|------------------------------------------------------------------------|
| 민감한 데이터 보호하기          | 데이터베이스 연결 정보, API 키, 사용자 비밀정보 등은 절대 클라이언트에 노출되면 안 됩니다. 서버 함수 내부에서만 접근하도록 하세요. |
| 데이터 검증 및 인가 처리       | 클라이언트 요청 시 입력값을 반드시 검증하고, 인증과 권한 체크를 통해 불법 접근을 막으세요.          |
| 에러 처리 및 로그 관리          | 서버 함수에서 발생하는 예외 처리를 신경쓰고, 보안 관련 로그는 적절히 기록해 두세요.            |
| XSS 및 Injection 공격 방지    | 쿼리를 생성할 때 SQL 주입 또는 스크립트 주입 공격을 방지하도록 준비된 쿼리 사용과 데이터 정제 수행. |

서버 함수는 서버 전용 코드임을 명확하게 표시하고, 클라이언트에서는 최소한의 정보만 주고받도록 하는 게 핵심입니다. 이런 방법들을 지키면 더욱 안전한 웹 애플리케이션 개발에 한 걸음 더 다가갈 수 있어요.

---

더 자세한 내용이 궁금하면, 사용하는 프레임워크 문서에서 `Server Functions` 또는 `Server Components` 부분을 참고해 보세요. `use server` 지시어를 어떻게 활용하는지, 그리고 클라이언트와 서버 간 데이터 흐름을 어떻게 구성하는지 실무에 큰 도움이 될 거예요!


<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>

### 인증(Authentication)과 인가(Authorization)

서버 쪽에서 중요한 작업을 수행할 때는 항상 사용자가 누구인지 인증(Authentication)하고, 그 작업을 할 권한이 있는지를 확인하는 인가(Authorization)를 먼저 하셔야 해요.

아래 예제 코드를 살짝 바꿔가며 설명해볼게요.

```js
import { db } from '@/lib/db' // 데이터베이스 클라이언트
import { authenticate } from '@/lib/auth' // 인증 라이브러리

export async function createUser(data, request) {
  const user = await authenticate(request) // 요청에서 사용자 인증
  
  if (!user) {
    throw new Error('Unauthorized') // 인증 실패 시 에러 처리
  }
  
  // 인증된 사용자만 새 사용자 생성 가능
  const newUser = await db.user.create({ data })
  return newUser
}
```

위 코드에서 중요한 포인트는 `authenticate` 함수를 통해 사용자의 신원을 확인하는 과정을 거친다는 점이에요. 인증이 안 된 상태로 `createUser` 같은 주요 작업을 진행한다면 보안 이슈가 생길 수 있으니 꼭 확인해야 합니다.

### 인증과 인가, 이 둘의 차이

- **인증(Authentication)**: "너 누구야?" 라며 사용자 신원을 확인하는 과정  
- **인가(Authorization)**: "너 이 작업 해도 돼?" 라며 권한을 확인하는 과정

예를 들어, 로그인된 사용자가 있더라도 그 사람이 게시글 삭제 권한이 없다면 삭제할 수 없게 막는 게 바로 인가 절차가 됩니다.

### 덧붙여서

API 설계 시 보통 토큰(JWT 등)을 활용한 인증 방식을 많이 사용해요. 그리고 권한 관리는 역할(Role) 기반으로 하거나 특정 권한을 부여하는 식으로 구현하는 게 실무에서 흔하죠.

또한, 프론트엔드에서도 인증 상태를 관리하고, 서버에는 절대 신뢰할 수 없는 상태로 요청하지 않는 게 중요합니다! 서버가 항상 “내가 진짜 인증한 사용자와 이야기 중인지”를 검증해야 한다는 점, 꼭 기억하세요.

---

## 참고 문서

- [OAuth 2.0 공식 문서](https://oauth.net/2/)
- [JWT 소개와 활용법](https://jwt.io/introduction)
- [Node.js Authentication Best Practices](https://blog.nodejs.org/2021/10/05/node-js-authentication-best-practices/)


<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 공식 문서에서 'use server'에 대한 자세한 내용을 확인할 수 있어요.  

'Use server'는 React 18부터 도입된 기능 중 하나로, 서버 컴포넌트를 사용할 때 주로 활용됩니다. 서버 컴포넌트를 통해 렌더링이 서버에서 이루어지기 때문에 클라이언트 사이드보다 초기 로딩 속도가 빠르고, SEO에도 좋다는 장점이 있어요.  

React 공식 문서에서는 'use server'가 어떻게 동작하는지, 그리고 서버 컴포넌트를 어떻게 잘 활용할 수 있는지 구체적으로 설명하고 있으니 직접 확인해보시면 많은 도움이 될 거예요.  

또한, 서버 컴포넌트는 데이터 요청(fetch) 같은 작업을 서버에서 직접 처리할 수 있어서 클라이언트의 부담을 줄여주는데, React의 'use server' 기능과 잘 결합하면 더욱 효과적이죠.  

궁금하다면 아래 React 공식 문서 링크에서 자세한 내용 읽어보세요!  
https://reactjs.org/docs/getting-started.html (React 공식 문서 메인 페이지입니다. 'Server Components'나 'use server'를 검색해보시면 도움됩니다.)  

필요하다면 관련 예제나 사용법도 같이 소개해드릴게요!

Next.js 15 서버 사이드 렌더링 사용법(use server)

# use client

React에서 `use client`는 컴포넌트를 클라이언트 사이드에서 렌더링하도록 지정하는 지시자입니다. 쉽게 말해, 사용자와 상호작용하는 UI, 예를 들면 상태 관리(state management), 이벤트 처리(event handling), 브라우저 API 접근 등이 필요할 때 이 지시자를 사용해요. 서버에서 렌더링되는 컴포넌트와 달리, 클라이언트 컴포넌트는 브라우저에서 직접 실행되기 때문에 좀 더 동적인 기능을 구현할 수 있죠.

## 사용법

컴포넌트를 클라이언트 컴포넌트로 만들고 싶다면, 파일 제일 상단에 `use client` 지시자를 추가하면 됩니다. 이 지시자는 모든 import문보다 먼저 위치해야 해요.

```jsx
"use client";

import React, { useState } from "react";

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      클릭 수: {count}
    </button>
  );
}

export default Counter;
```

> 여기서 중요한 점은 `"use client"`가 문자열로서 파일 맨 위에 위치해야 한다는 거예요. 만약 위치가 바뀌면 제대로 작동하지 않을 수 있어요.

---

### 추가 팁!

- React 18부터 도입된 이 기능은 Next.js 13 이상의 App Router와 함께 자주 사용돼요.
- 클라이언트 컴포넌트에는 서버 전용 데이터 페칭 기능을 직접 사용할 수 없으니, 필요한 데이터는 부모 서버 컴포넌트에서 미리 받아서 props로 전달하는 방식으로 설계해야 합니다.
- 너무 많은 컴포넌트에 `use client`를 붙이면 클라이언트 번들 크기가 커져서 로딩 속도에 영향을 줄 수 있으니, 필요한 부분에 집중해서 사용하는 게 좋아요.

`use client`를 잘 활용하면 React의 서버-클라이언트 경계에서 효율적인 UI 구성이 가능하답니다!


<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>

```jsx
import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  )
}
```

## 서버 컴포넌트 안에 클라이언트 컴포넌트 넣기

여러분, React 최신 트렌드인 서버 컴포넌트(Server Components)와 클라이언트 컴포넌트(Client Components)에 대해 들어보셨나요? 이 두 가지를 잘 섞으면 속도 빠르고 사용자와 상호작용이 뛰어난 앱을 만들 수 있답니다.

| 컴포넌트 종류      | 용도 및 특징                                         |
|------------------|---------------------------------------------------|
| 서버 컴포넌트       | 정적인 콘텐츠, 데이터 패칭, SEO 최적화에 적합          |
| 클라이언트 컴포넌트  | 상태 관리, 이벤트 핸들링, 브라우저 API 사용 등 동적 기능 담당 |
| 조합 방법           | 서버 컴포넌트 안에 필요한 UI에 클라이언트 컴포넌트를 넣어 사용 |

예를 들어, 서버에서 렌더링하는 부분은 정적으로 두고, 사용자가 버튼을 클릭해 카운터를 올리는 등 동적인 기능이 필요한 부분은 클라이언트 컴포넌트로 처리합니다.

이렇게 하면, 전체 앱의 초기 로딩 속도는 빠르면서도, 사용자와의 상호작용도 놓치지 않는 깔끔한 구조를 유지할 수 있어요.

추가로! 서버 컴포넌트는 기본적으로 클라이언트 상태나 이벤트를 직접 사용할 수 없기 때문에, 꼭 필요할 때만 클라이언트 컴포넌트를 분리해서 넣어주는 게 좋습니다. 이렇게 역할을 명확히 나누면, 코드 관리도 훨씬 수월해지고 최적화도 쉬워져요.

궁금하다면 직접 서버 컴포넌트에서 클라이언트 컴포넌트를 호출하는 예제를 찾아보면서 써보세요! React 18 이후부터 이런 방식이 점점 더 표준이 되고 있답니다.


<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>

다음 예시를 살펴볼게요:

- **Header**는 정적 콘텐츠를 처리하는 **서버 컴포넌트**입니다.
- **Counter**는 페이지 내에서 상호작용을 가능하게 하는 **클라이언트 컴포넌트**예요.

```js
import Header from './header'
 
export default function Page() {
  return (
    <div>
      <Header />
    </div>
  )
}
```

---

### 좀 더 쉽게 이해해볼까요?

서버 컴포넌트는 서버에서 렌더링되어 HTML 형태로 클라이언트로 전달돼요. 그래서 페이지를 빠르게 보여줄 수 있고, 초기 로드가 더 빨라지죠. 단, 서버 컴포넌트는 React 훅(useState, useEffect 등)을 사용할 수 없고, 사용자와 직접 상호작용하는 기능을 처리하는 데는 적합하지 않아요.

반대로 클라이언트 컴포넌트는 브라우저(클라이언트)에서 실행되므로, 사용자 입력에 반응하거나 실시간으로 변화하는 UI를 만들 수 있어요. 다만, 클라이언트 컴포넌트는 서버 컴포넌트보다 초기 로딩 시 무거울 수 있답니다.

---

### 간단 비교 테이블

| 구분         | 서버 컴포넌트          | 클라이언트 컴포넌트      |
| ------------ | --------------------- | ----------------------- |
| 실행 위치     | 서버                  | 브라우저(클라이언트)     |
| 상태 관리     | 불가능                | 가능                    |
| 렌더링 속도   | 빠름                  | 상대적으로 느림          |
| 사용자 상호작용 | 제한적                 | 자유롭게 가능            |
| 사용 예시     | 헤더, 정적 페이지 등   | 버튼, 폼, 카운터 등       |

---

이렇게 두 가지 컴포넌트의 역할을 잘 나누면, 성능과 개발 효율성을 모두 잡을 수 있습니다. 앞으로 Next.js나 React 최신 버전을 쓸 때 이 점 꼭 기억해 주세요! 필요하다면 서버 컴포넌트 안에서 클라이언트 컴포넌트를 불러 올 수도 있으니, 상황에 맞게 섞어서 써보는 것도 추천합니다.

필요한 자료가 더 있다면 언제든 알려주세요!


<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 문서에서 "use client"에 대해 더 자세히 알아볼 수 있어요.

사실 "use client"는 React 18부터 도입된 개념이라, 클라이언트 사이드 렌더링을 명확히 구분하고자 할 때 많이 사용돼요. 예를 들어, Next.js 13처럼 React 18 기반 프레임워크에서는 서버 컴포넌트와 클라이언트 컴포넌트를 구분해서 작성하는 게 중요하거든요.

"‘use client’"라는 지시어를 컴포넌트 파일 상단에 적으면, 이 컴포넌트가 클라이언트 쪽에서 실행된다는 걸 명확히 알릴 수 있어요. 그럼 그 컴포넌트 안에 useState, useEffect 같은 React 훅들을 편하게 쓸 수 있답니다.

더 자세한 내용과 공식 가이드는 리액트 공식 문서에서 확인해 보세요! 여기에 간단 링크도 남겨 둘게요.

- [React 공식 문서 - Client Components](https://reactjs.org/docs/client-components.html) (영문)  
- Next.js에서 클라이언트 컴포넌트 사용하는 방법도 참고하면 좋아요

이외에 React 18을 쓰면서 새로운 컴포넌트 구분법에 대해 궁금한 점 있으면 언제든 물어봐 주세요!

Next.js 15에서 클라이언트 사이드 렌더링 하는 방법 (use client)

Next.js 15에서 Cache 사용법 및 성능 최적화 방법 정리

Next.js 15로 만드는 2025년 최신 Progressive Web Application (PWA)

Next.js 15 디버깅 가이드 - 오류 추적과 해결 방법

# 커스텀 서버(Custom Server) 이해하기

Next.js를 사용하면 기본적으로 `next start` 명령어로 내장된 서버가 바로 실행돼요. 그런데 만약 이미 백엔드 서버가 따로 있다면, 그걸 그대로 유지하면서 Next.js와 함께 사용할 수도 있답니다. 이 경우를 ‘커스텀 서버(Custom Server)’라고 부르지 않아요.

커스텀 Next.js 서버는 필요에 따라 내 프로그램에서 직접 서버를 띄우면서 라우팅이나 요청 처리 방식을 자유롭게 바꾸고 싶을 때 사용해요. 하지만 대부분의 경우에는 Next.js가 제공하는 기본 라우터만으로도 충분하기 때문에 굳이 커스텀 서버를 만들 필요가 없어요.

> **여기서 주의!**
>
> - 커스텀 서버는 Next.js의 자동 정적 최적화(Automatic Static Optimization) 같은 중요한 성능 개선 기능들을 포기하는 대가를 치러야 해요.
> - 그리고 Vercel 같은 Next.js 공식 배포 플랫폼에서는 커스텀 서버를 사용할 수 없어요.
> - `standalone` 출력 모드를 사용할 때는 커스텀 서버 파일을 함께 추적하지 않고, 대신 최소한의 `server.js` 파일만 따로 만들어내요. 그래서 둘을 동시에 사용할 수도 없으니 주의가 필요해요.

아래는 커스텀 서버의 간단한 예시를 보여드릴게요. 예전에는 Express.js 같은 외부 서버 라이브러리와 함께 Next.js를 이렇게 쓰는 경우가 많았는데, 최근 Next.js가 점점 더 자체 기능을 강화하면서 점차 필요성이 줄고 있죠.

```js
const express = require("express");
const next = require("next");

const port = 3000;
const app = next({ dev: false });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = express();

  // 커스텀 라우트 예시
  server.get("/p/:id", (req, res) => {
    const actualPage = "/post";
    const queryParams = { id: req.params.id };
    app.render(req, res, actualPage, queryParams);
  });

  // 나머지는 Next.js 기본 처리
  server.all("*", (req, res) => {
    return handle(req, res);
  });

  server.listen(port, (err) => {
    if (err) throw err;
    console.log(`> Ready on http://localhost:${port}`);
  });
});
```

---

### 꼭 알아두면 좋은 팁

- 커스텀 서버는 정말 필요할 때에만 써요! 기본 Next.js 라우팅으로 충분하면 굳이 복잡하게 서버를 직접 관리할 필요 없어요.
- Vercel 배포에서는 사용 불가라는 점, 잊지 마세요.
- 서버 없는 환경(serverless)이나 요즘 많이 쓰는 ISR(Incremental Static Regeneration) 기능이랑도 잘 맞지 않아요.
- 많이 쓰이는 기능은 공식 Next.js 라우터 기능이나 API 라우트를 활용하는 게 더 깔끔하고 이후 유지보수도 편해요.

만약 커스텀 서버와 관련해서 더 궁금한 점 있으면 언제든 질문해 주세요! 혹은 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>

Next.js 프로젝트에서 커스텀 서버를 직접 만들고 싶을 때, 보통 `server.js` 파일을 만들어서 Node.js의 HTTP 서버를 활용하곤 해요. 오늘은 간단한 커스텀 서버 예제와, 이걸 어떻게 실행할지 package.json에 스크립트를 어떻게 추가하는지 알려드릴게요.

먼저, 이 코드를 보시면 서버를 직접 생성하고 Next.js 앱을 `next()` 함수로 감싼 뒤에 준비가 끝나면 HTTP 서버를 띄우는 구조예요.

```js
import { createServer } from 'http'
import { parse } from 'url'
import next from 'next'

const port = parseInt(process.env.PORT || '3000', 10)
const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    const parsedUrl = parse(req.url!, true)
    handle(req, res, parsedUrl)
  }).listen(port)

  console.log(
    `> Server listening at http://localhost:${port} as ${
      dev ? 'development' : process.env.NODE_ENV
    }`
  )
})
```

이 코드에서 핵심은 `app.prepare()`가 끝나면 HTTP 서버를 열며, 들어오는 요청을 `handle` 함수로 넘겨서 Next.js가 페이지를 렌더링하도록 한다는 점이에요.

### 그런데 여기서 중요한 점!

`server.js`는 Next.js 컴파일러를 거치지 않고 그냥 Node.js에서 직접 실행되기 때문에, 최신 문법(예: ES 모듈 `import` 구문)을 쓸 때 Node.js 버전과 호환되는지 반드시 확인해야 합니다. 만약 호환 안 되면 직접 `require()`로 바꾸거나, Babel 같은 트랜스파일러 사용을 고려해야 해요.

---

### package.json에 커스텀 서버 실행 스크립트 추가하기

커스텀 서버를 실행하려면 `package.json`의 `scripts`를 이렇게 바꿔줘야 해요.

```json
{
  "scripts": {
    "dev": "node server.js",
    "build": "next build",
    "start": "NODE_ENV=production node server.js"
  }
}
```

- `dev`: 개발 모드에서 커스텀 서버 바로 실행
- `build`: Next.js 빌드 수행
- `start`: 프로덕션 환경에서 커스텀 서버 실행

---

### 덧붙여서…

커스텀 서버를 만들면 유연하게 서버 로직 제어가 가능하지만, Next.js의 기본 서버 기능과 자동 최적화, 배포 플랫폼(예: Vercel) 지원을 덜 받게 돼요. 그러니 정말 필요한 경우가 아니라면 기본 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>

대신에 nodemon을 설정해서 사용할 수도 있어요(예시 참고). 커스텀 서버는 Next.js 애플리케이션과 연결하기 위해 아래와 같은 import 문을 사용합니다:

```js
import next from "next";

const app = next({});
```

여기서 next 함수는 옵션들을 담은 객체를 인자로 받는데요, 주요 옵션들은 다음과 같습니다:

| 옵션         | 타입               | 설명                                                                                |
| ------------ | ------------------ | ----------------------------------------------------------------------------------- |
| `conf`       | `Object`           | `next.config.js` 에서 사용하는 설정 객체와 동일해요. 기본값은 `{}` 입니다.          |
| `dev`        | `Boolean`          | (선택) Next.js를 개발 모드로 실행할지 여부입니다. 기본값은 `false` 입니다.          |
| `dir`        | `String`           | (선택) Next.js 프로젝트 위치를 지정합니다. 기본값은 현재 폴더 `'.'` 입니다.         |
| `quiet`      | `Boolean`          | (선택) 서버 정보가 포함된 에러 메시지를 숨길지 결정합니다. 기본값은 `false` 입니다. |
| `hostname`   | `String`           | (선택) 서버가 실행되는 호스트 이름을 지정합니다.                                    |
| `port`       | `Number`           | (선택) 서버가 실행되는 포트를 지정합니다.                                           |
| `httpServer` | `node:http#Server` | (선택) Next.js가 작동 중인 HTTP 서버 객체를 넘겨줄 수 있습니다.                     |
| `turbo`      | `Boolean`          | (선택) Turbopack을 활성화할지 여부입니다.                                           |

---

**간단 팁!**

- 개발할 때 `dev` 옵션을 `true`로 주면 핫 리로딩도 잡아주고 디버깅이 편해져요.
- 프로젝트 경로가 현재 폴더가 아니라면 `dir` 옵션으로 정확히 지정해주는 게 중요합니다.
- `quiet` 옵션을 켜면 서버 에러 로그가 줄어들어 콘솔이 깔끔해져서 가끔 쓰면 좋아요.
- 그리고 마지막으로 `turbo` 옵션은 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>

반환된 앱은 Next.js가 요청을 필요한 대로 처리할 수 있도록 사용하는 데 활용할 수 있어요.

여기서 중요한 점은, Next.js가 기본적으로 서버 사이드 렌더링(SSR)과 정적 생성(SSG) 모두를 지원하기 때문에, 반환된 앱으로 다양한 요청 처리 방식을 유연하게 다룰 수 있다는 거예요.

예를 들어, API 라우트나 커스텀 서버를 구축할 때 조금 더 세밀한 제어가 필요하면 이렇게 반환된 앱을 통해 요청을 직접 처리할 수 있고, 그렇지 않으면 Next.js의 기본 라우팅에 맡길 수도 있죠.

이런 방식을 활용하면 복잡한 서버 로직을 구현할 때도 Next.js의 장점을 최대한 살리면서 개발할 수 있어요!

Next.js 15 커스텀 서버 구축하는 방법

Nextjs15에서 로컬 개발 환경 구축하는 방법

# 패키지 번들링 최적화하기

외부 패키지를 번들링하면 애플리케이션의 성능을 크게 향상시킬 수 있어요. Next.js에서는 기본적으로 Server Components와 Route Handlers 안에서 임포트한 패키지들을 자동으로 번들링해줍니다. 이번 글에서는 패키지 번들링을 어떻게 분석하고, 더 최적화할 수 있는지 알려드릴게요.

## 자바스크립트 번들 분석하기

`@next/bundle-analyzer`는 Next.js에서 사용 가능한 플러그인으로, 애플리케이션 번들의 크기를 관리하는 데 도움을 줍니다. 이 플러그인은 각 패키지와 그 의존성들의 크기를 시각적으로 보여주는 리포트를 만들어줘서, 큰 크기의 패키지를 찾아내거나 코드 스플리팅, 혹은 지연 로딩(lazy loading)을 적용하는 데 활용할 수 있죠.

### 추가 팁!

- 번들 크기가 예상보다 크다면, 대체할 수 있는 가벼운 라이브러리가 있는지 찾아보세요.
- 필요하지 않은 패키지는 과감히 삭제하는 것도 중요합니다.
- 코드 스플리팅을 활용해 페이지별로 필요한 코드만 로드하는 것도 좋은 방법이에요.

필요하다면 `package.json`에 아래 명령어를 추가해서 쉽게 번들 분석을 실행할 수 있습니다.

```json
"scripts": {
  "analyze": "cross-env ANALYZE=true next build"
}
```

그리고 터미널에서 `npm run analyze` 또는 `yarn analyze` 명령어를 실행하면, 번들 분석 리포트가 뜹니다.

패키지 번들 사이즈를 잘 관리하면 로딩 속도가 빨라지고 사용자 경험이 훨씬 좋아지니 꼭 신경 써보세요!


<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>

### 설치 방법

플러그인을 설치하려면 아래 명령어 중 하나를 터미널에 입력하세요:

```bash
npm i @next/bundle-analyzer
# 또는
yarn add @next/bundle-analyzer
# 또는
pnpm add @next/bundle-analyzer
```

그다음, `next.config.js` 파일에 번들 분석기 설정을 추가해주면 됩니다.

---

참고로, `@next/bundle-analyzer`는 Next.js 프로젝트에서 번들 크기를 시각적으로 확인할 수 있게 도와줘서, 최적화 작업할 때 정말 유용한 도구예요. 어떤 파일이 용량이 큰지, 어디에 리소스를 많이 쓰는지 쉽게 파악할 수 있거든요.

`next.config.js`에 설정하는 예시는 다음과 같아요:

```js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // 기존 Next.js 설정들...
});
```

실행할 때 `ANALYZE=true` 환경 변수를 주면 번들 분석기가 활성화되고, 그렇지 않으면 비활성화되어 평상시에는 빌드 속도에 영향을 주지 않아요.

이를 통해 필요할 때만 번들 분석기를 켜고, 평상시에는 쾌적한 개발 환경을 유지할 수 있습니다!


<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/bundle-analyzer` 패키지를 활용하면 됩니다.

먼저, `next.config.js` 파일에 아래처럼 설정을 추가해 주세요:

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

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})

module.exports = withBundleAnalyzer(nextConfig)
```

여기서 핵심은 `ANALYZE` 환경 변수를 `true`로 설정해서, 번들 분석 기능을 켜는 거예요. 실제 빌드를 할 때만 분석기가 동작하도록 설정해서, 평소에는 성능에 영향이 없도록 해 줍니다.

분석 보고서를 보려면, 아래 명령어 중 하나를 내리면 끝!

```bash
ANALYZE=true npm run build
# or
ANALYZE=true yarn build
# or
ANALYZE=true pnpm build
```

이렇게 하면, 빌드가 완료된 후에 `.next` 폴더 안에 번들 분석 리포트가 생성되는데요, 기본적으로는 브라우저에서 시각적인 트리맵 형태를 확인할 수 있어요.

---

### 조금 더 팁!

- 번들 분석기를 쓰는 이유는 무엇일까요? 프로젝트가 커질수록 예상치 못한 패키지가 번들에 포함되거나, 너무 큰 라이브러리가 들어가서 페이지 로딩 속도가 느려질 수 있어요. 이걸 시각적으로 확인하고 최적화 방향을 잡을 수 있답니다.
- `withBundleAnalyzer`처럼 Next.js는 여러가지 플러그인 형태의 설정을 감싸서 사용할 수 있어요. 만약 다른 기능을 같이 쓰는 중이라면 `compose` 형태로 합쳐주는 방법도 찾을 수 있습니다.
- 만약 자동으로 보고서를 열고 싶다면, 추가 설정을 주거나 별도의 스크립트를 작성해도 좋습니다.

이제 내 프로젝트 번들이 얼마나 크고, 어디에 무거운 부분이 있는지 손쉽게 분석해 보세요! 개발할 때 정말 큰 도움이 될 거예요.


<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 파일에 `optimizePackageImports` 옵션을 추가해보세요. 이 설정을 하면 실제로 사용하는 모듈만 로딩해서 불필요한 코드가 빠져나가거든요. 게다가 여전히 여러 개의 네임드 익스포트를 사용하는 것처럼 깔끔하게 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>

Next.js 설정에서 `optimizePackageImports`와 `serverExternalPackages` 옵션에 대해 알아볼게요.

---

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: ['icon-library'],
  },
}

module.exports = nextConfig
```

위 코드는 `experimental.optimizePackageImports`에 `'icon-library'`라는 특정 라이브러리를 넣어둔 모습인데요, 이 옵션은 Next.js가 이 라이브러리를 임포트할 때 최적화하도록 지시하는 역할을 해요.

### 자동 최적화되는 라이브러리가 있다?!  
사실 Next.js는 기본적으로 자주 쓰이는 몇몇 라이브러리들을 알아서 최적화해주고 있어서, 모든 라이브러리를 `optimizePackageImports`에 적어줄 필요는 없답니다. 예를 들어 React, lodash 등 자주 쓰이는 라이브러리는 이미 최적화 대상에 포함되어 있어서 따로 추가 안 해도 된다구요.  
> [Next.js 공식 문서](https://nextjs.org/docs/pages/building-your-application/configuring/optimizing-packages#opt-in-to-automatic-package-import-optimization)에서 최적화 대상 라이브러리 ‘풀 리스트’를 확인할 수 있어요. 

### 서버 사이드에서 번들링 제외하기  

Next.js에서는 **서버 컴포넌트(Server Components)** 와 **라우트 핸들러(Route Handlers)** 내부에서 임포트한 패키지들은 기본적으로 번들링되어 배포돼요. 근데 가끔씩은, 특정 패키지를 번들링 대상에서 제외하고 싶을 때가 있습니다. 이럴 때는 `serverExternalPackages` 옵션을 사용하면 되는데요! 예를 들면 이렇게요:

```js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverExternalPackages: ['some-server-only-package'],
  },
}

module.exports = nextConfig
```

`serverExternalPackages`에 등록한 패키지는 서버 번들에서 제외되고, 런타임에 직접 Node.js 환경에서 불러와 사용하게 됩니다. 이러면 서버 번들 크기를 좀 더 가볍게 유지하거나, 예를 들어 네이티브 모듈이나 빌드 시점에 번들링 불가능한 라이브러리를 다룰 때 도움이 돼요.

---

### 정리하자면  

| 설정 옵션               | 역할                                                         |
|------------------------|------------------------------------------------------------|
| `experimental.optimizePackageImports` | 특정 클라이언트 라이브러리를 import 최적화하도록 설정        |
| `experimental.serverExternalPackages` | 서버 컴포넌트, 라우트 핸들러 번들에서 제외할 패키지를 지정함   |

이 옵션들은 `experimental`이 붙어있는걸로 보아 아직 완전히 안정화된 기능은 아니지만, 프로젝트에 맞게 적절히 활용하면 번들 크기 최적화에 꽤 도움이 될 수 있어요.

---

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>

안녕하세요 여러분! 오늘은 Next.js에서 `serverExternalPackages` 옵션에 대해 간단히 이야기해보려고 해요. 

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

module.exports = nextConfig
```

위 코드처럼 `next.config.js`에 `serverExternalPackages`에 외부 패키지 이름을 명시해주면, Next.js 서버 쪽에서 해당 패키지를 외부 모듈로 처리하도록 설정할 수 있어요. 

이 옵션은 서버에서만 사용하는 패키지나, Next.js가 기본적으로 번들링하지 않는 패키지를 명시할 때 유용합니다. 특히 서버 사이드에서 동작하는 Node.js 패키지를 사용할 때 문제가 발생할 수 있는데, 이때 `serverExternalPackages`에 해당 패키지를 추가해주면 해결되곤 하죠.

> 참고로 Next.js가 이미 호환성을 검증하고 자동으로 제외 처리하는 인기 패키지 목록이 따로 있어요. 여러분이 직접 추가하기 전에 [Next.js 공식 문서](https://nextjs.org/docs)에서 지원하는 패키지 리스트를 확인해보는 게 좋아요. 이렇게 하면 중복 설정을 줄일 수 있거든요!

---
추가로 팁을 드리자면, 서버 외부 패키지를 추가할 때는 버전 호환성도 꼭 체크하세요. Next.js가 업데이트되면서 패키지 호환성도 변화할 수 있습니다. 그리고 외부 패키지를 너무 많이 추가하면 번들링 최적화가 어려워질 수 있으니 꼭 필요한 패키지만 추가하는 걸 추천해드려요.

필요하면 Next.js의 Webpack 설정을 커스텀해서 좀 더 세밀한 번들링 조정도 가능합니다. 나중에 기회되면 Webpack 설정과 함께 리뷰해볼게요!

궁금한 점 있으면 댓글 남겨주세요~ 개발 재미있게 함께 해봐요! 🚀

Next.js 15에서 패키지 번들링 최적화하는 방법

# 부분 프리렌더링 (Partial Prerendering)

> 참고: 부분 프리렌더링은 아직 실험적인 기능으로, Next.js의 캐나리 버전에서만 사용 가능하며 추후 변경될 수 있습니다. 아직 프로덕션용으로는 적합하지 않아요.

부분 프리렌더링은 한 경로(Route) 내에서 정적인 컴포넌트와 동적인 컴포넌트를 동시에 사용할 수 있게 해 주는 기능입니다.

어떻게 동작하냐면, 빌드 타임에 Next.js가 가능한 한 경로의 내용을 미리 렌더링해줍니다. 그런데 만약 동적 코드를 발견했다면(예를 들면, 들어오는 요청에서 데이터를 읽는다거나 할 때), 그 부분을 React Suspense 경계로 감싸줄 수 있어요. 이렇게 Suspense로 감싸진 컴포넌트는 빌드 시점에 실제 동적 데이터 대신 'fallback' UI가 미리 렌더링된 HTML로 포함됩니다.

즉, 정적인 부분은 그대로 미리 렌더링하고, 동적인 부분은 사용자가 페이지를 요청할 때 불러오는 방식을 섞어 쓸 수 있는 거죠.

---

### 조금 더 쉽게 이야기하면?

보통 Next.js의 정적 페이지는 모든 내용을 빌드할 때 미리 만들어 놓아요. 그런데 동적인 데이터가 있으면 빌드할 때 알 수 없으니 SSR(서버 사이드 렌더링) 방식으로 페이지를 채우죠. Partial Prerendering은 이 두 가지 방식을 한 페이지에서 섞어 쓸 수 있게 해 줍니다.

React Suspense를 잘 활용할 줄 안다면, 특정 컴포넌트에서 데이터를 읽는 부분만 동적으로 처리하고, 나머지는 미리 만들어진 HTML로 빠르게 보여줄 수 있다는 뜻입니다.

---

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

- 현재는 실험적인 기능이니 코드에 적용할 때는 주의하세요.
- Suspense fallback UI가 어떻게 보일지 신경 써야 합니다. 너무 단순하면 사용자 경험이 떨어질 수 있어요.
- 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>

<img src="/TIL/assets/img/2025-04-22-PartialPrerendering_0.png" alt="Partial Prerendering illustration" />

> 🎥 영상: PPR이 뭔지, 어떻게 동작하는지 궁금하다면 → YouTube에서 10분짜리 동영상으로 확인해보세요!

---

## 배경 이야기

Partial Prerendering (부분 사전 렌더링, 이하 PPR)은 Next.js 서버가 미리 렌더링된 콘텐츠를 즉시 클라이언트에 전달할 수 있도록 도와주는 기술이에요.

사실, 웹 페이지를 렌더링할 때 서버가 완전히 렌더링을 마치지 않았는데도 이미 사용자에게 콘텐츠를 보여줄 수 있으면, 빠른 첫 화면 로딩을 경험할 수 있죠. PPR은 그걸 가능하게 합니다.

실제로 개발해보면, 전체 페이지를 미리 렌더링하는 것보다 특정 중요한 부분만 미리 렌더링하고, 나머지는 필요할 때 로드하게끔 하는 전략이 성능 최적화에 엄청 효과적이라는 걸 알 수 있어요.

필요한 부분만 빠르게 보여주고, 나머지는 나중에 채우는 이 방법! 여러분 프로젝트에도 적용해보시면 사용자 체감 속도가 확 올라간답니다. 다음 글에서는 PPR을 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>

클라이언트에서 서버로 이어지는 워터폴 문제를 막기 위해, 동적 컴포넌트들은 초기 프리렌더링과 함께 서버에서 병렬로 스트리밍되기 시작합니다. 이렇게 하면 클라이언트의 자바스크립트가 브라우저에 완전히 로드되기 전에 동적 컴포넌트가 렌더링을 시작할 수 있어 사용자 경험이 훨씬 부드러워집니다.

또한, 각각의 동적 컴포넌트마다 HTTP 요청을 여러 번 보내는 것을 막기 위해 부분 프리렌더링(Partial Prerendering, PPR)은 정적 프리렌더와 동적 컴포넌트를 하나의 HTTP 요청으로 합칠 수 있습니다. 이 덕분에 동적 컴포넌트마다 네트워크 왕복(roundtrip)이 발생하지 않고, 전체적인 로딩 속도가 크게 개선돼요.

## 부분 프리렌더링(Partial Prerendering) 사용법

### 점진적 도입 (버전 15 캐나리 버전 기준)

---

추가로, 이런 방식은 특히 대규모 애플리케이션에서 효과적이에요. 서버에서 먼저 준비된 콘텐츠를 빠르게 보여주면서도, 필요한 부분은 필요한 시점에만 동적으로 로딩하니 네트워크 자원도 효율적으로 사용할 수 있죠.

또한, 만약 여러분이 React나 Next.js 같은 프레임워크를 쓴다면, 이 Partial Prerendering 기능을 잘 활용하면 SEO 측면에서도 유리하고 초기 렌더링 퍼포먼스도 개선할 수 있어요. 초기 페이지 로딩 후 바로 상호작용할 수 있게 만드는 ‘경량화’ 전략이라고 생각하면 이해가 쉬울 거예요.



<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 15 최신 캐나리(canary) 버전에서 'Partial Prerendering(PPR)' 기능이 실험적으로 도입되었어요. 아쉽게도 아직 안정화 버전에는 포함되어 있지 않습니다. 혹시나 미리 사용해보고 싶다면 캐나리 버전을 설치해야 하는데요, 아래 명령어를 터미널에 입력하면 됩니다.

```bash
npm install next@canary
```

설치 후에는 프로젝트의 `next.config.js` 파일을 열어서 `ppr` 옵션을 `'incremental'`로 설정해 주세요. 그리고 다음과 같이 `experimental` 설정 안에 넣어주면 되는데요:

```js
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    ppr: "incremental",
  },
};

export default nextConfig;
```

그리고 페이지나 레이아웃 파일 상단에서 `experimental_ppr` 라우트 구성 옵션을 내보내면 부분 프리렌더링을 점진적으로 적용할 수 있어요.

> 참고로, Partial Prerendering은 렌더링되지 않은 부분만 클라이언트에서 처리하면서도, 전체 페이지는 정적으로 일부 미리 렌더링하는 기술이에요. 그래서 초기 로딩은 빠르게 하면서도 일부 동적 변경이 가능한 유연한 페이지 구성이 가능하답니다.

다만, 아직 실험 단계기 때문에 사용하면서 생길 수 있는 문제에 대비해 꼭 테스트 환경에서 충분히 점검하는 걸 추천드려요. 안정 버전이 나오면 더 많은 업데이트와 공식 문서가 함께 제공될 테니 주목해 주세요!



<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)에서 실험적 기능인 `experimental_ppr`(Partial Prerendering)를 활용하는 코드와 관련하여 알아두면 좋은 내용들을 정리해볼게요. 조금 쉽게 설명해볼게요!

먼저, 제공된 코드를 보면 이렇게 생겼어요:

```js
import { Suspense } from "react";
import { StaticComponent, DynamicComponent, Fallback } from "@/app/ui";

export const experimental_ppr = true;

export default function Page() {
  return (
    <>
      <StaticComponent />
      <Suspense fallback={<Fallback />}>
        <DynamicComponent />
      </Suspense>
    </>
  );
}
```

---

## 핵심 포인트! `experimental_ppr`란?

- Next.js에서는 각 라우트별로 부분 프리렌더링을 할 수 있어요. (PPR)
- **PPR(Partial Prerendering)**를 활용하려면, 라우트 최상위에 `export const experimental_ppr = true`를 반드시 선언해야 해요.
- 만약 선언하지 않으면, 기본값은 `false`로 설정되어서 **프리렌더링이 되지 않아요**.
- 이 설정은 해당 라우트뿐만 아니라, 그 아래 자식 라우트나 레이아웃까지 적용돼요.
- 자식 라우트에서 PPR을 끄고 싶으면 자식 라우트에 `experimental_ppr = false`를 설정하면 됩니다.

즉, `experimental_ppr` 옵션은 라우트 트리에서 상위(루트) 영역에만 넣으면 자식까지 적용이 돼서 여러 파일에 일일이 선언할 필요 없어요.

---

## Suspense와 dynamic components (동적 컴포넌트) 이야기

PPR을 사용하는 라우트에서, Next.js 빌드 시에 반드시 동적 API 호출을 포함하는 컴포넌트는 `React.Suspense`로 감싸줘야 해요.

- `Suspense`가 없다면 자동 프리렌더링이 제대로 작동하지 않아요.
- `Suspense fallback`은 프리렌더된 페이지에서 **유저가 로딩 중일 때 보여질 UI**를 담당해줘요.
- 위 코드에서는 `<Fallback />` 컴포넌트를 로딩 중임을 보여주기 위해 넣었죠!

---

## 추가로 알아두면 좋은 것들

### 1. 왜 PPR을 쓰는 걸까?

전통적인 SSR은 모든 데이터를 서버에서 다 받아와서 렌더링해버려서, 느린 API나 복잡한 로직이 있으면 전체 페이지 로딩 시간이 느려질 수 있어요.

PPR은 정적 생성(Static Generation)과 SSR의 중간 느낌으로, "정적 프리렌더링 중 동적 컴포넌트만 나중에 클라이언트 쪽에서 로딩"하는 방식이에요.

덕분에:

- 페이지 첫 로딩은 빠르면서도,
- 자주 바뀌는 동적인 부분은 필요한 시점에만 로딩 가능해요.

### 2. `export const experimental_ppr = true`는 실험 기능!

현재는 아직 실험 단계라서 문서나 API가 조금씩 바뀔 수 있어요. 프로덕션 서비스라면 주의해서 사용해야 하죠.

---

## 요약해서 정리한 표!

| 내용                 | 설명                                                               |
| -------------------- | ------------------------------------------------------------------ |
| `experimental_ppr`   | 라우트(또는 세그먼트)에 프리렌더링을 활성화하는 플래그             |
| 기본값               | false                                                              |
| 적용범위             | 상위 세그먼트에만 선언하면 하위(자식 라우트, 레이아웃)에도 적용됨  |
| 동적 컴포넌트 감싸기 | 동적 로딩 컴포넌트는 React Suspense로 감싸야 하며 fallback UI 필요 |
| fallback UI          | 로딩 중 보여줄 UI. 보통 스피너나 텍스트 형태의 임시 UI를 넣음      |
| 사용 목적            | 빠른 페이지 로딩 & 프리랜더링과 동적 API 호출의 적절한 조화        |
| 주의점               | 아직 실험 기능이므로 버전 업에 따라 동작 변경 가능                 |

---

이렇게 `experimental_ppr`와 Suspense를 잘 활용하면 Next.js 앱에서 빠르고 유연한 프리렌더링을 경험할 수 있어요!

필요하면 더 자세한 예제나, 로딩 UI 디자인 팁도 공유할 수 있으니, 언제든 요청해 주세요. 😊



<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
import { cookies } from "next/headers";

export async function User() {
  const session = (await cookies()).get("session")?.value;
  return "...";
}
```

위 코드에서 `User` 컴포넌트는 들어오는 요청(request)을 보고 쿠키를 읽어야 해서, 이 컴포넌트를 PPR(Pre-Rendering with React)로 사용하려면 Suspense로 감싸줘야 합니다.

Vue에서는 Suspense가 없지만, React에선 비동기 처리를 하면서도 사용자 경험을 끊기지 않게 해주는 좋은 기능이에요. 예를 들면 이렇게요:

```js
import { Suspense } from "react";
import { User, AvatarSkeleton } from "./user";

export const experimental_ppr = true;

export default function Page() {
  return (
    <section>
      <h1>This will be prerendered</h1>
      <Suspense fallback={<AvatarSkeleton />}>
        <User />
      </Suspense>
    </section>
  );
}
```

여기서 핵심은 `Suspense`의 `fallback` 프로퍼티에 로딩 상태에서 보여줄 UI를 넣어준다는 점이에요. 예시에서는 `AvatarSkeleton`이 그 역할을 하죠. 즉, `User` 컴포넌트가 쿠키를 읽어 세션 정보를 가져올 때까지 사용자에게 깜빡이며 로딩 중임을 알려주고, 완료되면 실제 UI를 렌더링하는 거죠.

이렇게 하면 서버에서 미리 렌더링하는 부분과, 클라이언트에서 비동기적으로 받아와야 할 데이터가 함께 있어도 깔끔하게 처리할 수 있습니다. 특히 Next.js 최신 버전에서 SSR과 클라이언트 사이드 데이터 fetching을 조합할 때 정말 유용해요.

추가 팁을 드리자면:

- `cookies()` 같은 함수는 서버 측에서만 호출 가능해요. 클라이언트 컴포넌트에선 사용할 수 없으니 주의하세요.
- Suspense를 활용하면서 데이터 fetching이 비동기임을 명확히 해줘야 하므로, 해당 컴포넌트는 async 함수로 작성하고 반드시 프로미스를 반환해야 해요.
- PPR을 실험적으로 사용한다면, 나중에 정식 지원 상태를 꼼꼼히 확인하는 게 좋습니다. API가 변할 수도 있으니까요!

요약하자면, 서버에서 요청별로 쿠키를 읽어야 하면, 해당 컴포넌트를 Suspense로 감싸서 로딩 상태를 관리하며 안전하게 렌더링하는 패턴! 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>

리액트 컴포넌트가 언제 '동적 렌더링(dynamic rendering)'을 하게 될까요? 바로 컴포넌트 내부에서 특정 값을 실제로 사용할 때입니다.

예를 들어, Next.js 페이지에서 `searchParams`를 받아 이를 자식 컴포넌트에 prop으로 넘긴 상황을 생각해볼게요:

```js
import { Table } from "./table";

export default function Page({ searchParams }: { searchParams: Promise<{ sort: string }> }) {
  return (
    <section>
      <h1>This will be prerendered</h1>
      <Table searchParams={searchParams} />
    </section>
  );
}
```

위 코드에서 `Page` 컴포넌트는 `searchParams`를 받아서 내부 `Table` 컴포넌트로 전달하고 있는데요. 중요한 점은, 이 `Page` 컴포넌트 자체는 프리렌더링(정적 생성)이 되지만, `Table` 컴포넌트 안에서 이 `searchParams` 값을 실제로 읽으면, `Table`만 동적 렌더링 상태로 전환됩니다.

즉, 부모는 정적으로 렌더링 되다가, 자식에서 비동기 값을 접근하는 순간 그 자식 컴포넌트는 실시간으로 렌더링되는 거죠. 이런 방식으로 불필요한 동적 렌더링을 방지하면서, 꼭 필요한 부분만 동적으로 처리할 수 있는 효율적인 구조가 완성됩니다.

---

추가로, 만약 `searchParams`를 여러 군데서 반복해서 사용한다면, 값을 미리 받아서 context에 저장하거나 캐싱하는 방법도 좋아요. 그래야 여러 컴포넌트에서 같은 값을 비동기로 반복 요청하는 부담을 줄일 수 있죠. 개발하면서 이런 패턴을 잘 활용하면 렌더링 성능과 사용자 경험이 꽤 좋아질 거예요!



<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 컴포넌트에서 `searchParams`를 비동기 함수로 받아올 때 주의할 점에 대해 같이 살펴볼게요.

아래 예제를 보실까요?

```js
export async function Table({ searchParams }: { searchParams: Promise<{ sort: string }> }) {
  const sort = (await searchParams).sort === "true";
  return "...";
}
```

여기서 `searchParams`가 `{ sort: string }` 객체를 반환하는 Promise네요. 그래서 컴포넌트 함수 앞에 `async` 키워드를 붙이고, `await`로 값을 받아옵니다.

하지만 React 컴포넌트에서 이렇게 `async` 함수를 직접 쓰는 게 늘 좋은 방식은 아니에요. 왜냐하면 컴포넌트 자체가 렌더링 시 동기적으로 작동하는 걸 기대하기 때문에, 여기에 비동기 처리를 넣으면 의도치 않은 동작이나 렌더링 지연이 발생할 수 있거든요.

그래서 보통은 이런 식으로:

- `getServerSideProps` (Next.js) 같은 서버사이드 데이터 로딩 함수에서 데이터를 먼저 받고,
- 데이터를 props로 내려받아 컴포넌트는 동기적으로 렌더링하는 게 깔끔해요.

만약 Next.js의 **App Router**를 사용중이라면, 페이지나 UI 컴포넌트에서 `searchParams`는 이미 동기적인 객체로 제공됩니다. 그래서 이렇게 쓸 수 있죠:

```tsx
type TableProps = {
  searchParams: { sort?: string };
};

export default function Table({ searchParams }: TableProps) {
  const sort = searchParams.sort === "true";
  return <div>정렬 상태: {sort ? "활성화" : "비활성화"}</div>;
}
```

마지막으로 `sort` 값을 단순히 문자열 `"true"`와 비교했는데, 혹시 `"true"`나 `"false"` 외에 다양한 값이 올 수도 있으니 `Boolean` 변환이나 다른 검증 로직도 상황에 맞게 활용해보세요!

---

### 짧은 요약

| 문제점                                           | 해결법                                                                  |
| ------------------------------------------------ | ----------------------------------------------------------------------- |
| 컴포넌트를 `async` 함수로 만들어 비동기 받아오기 | 서버사이드 또는 별도 데이터 fetching 함수로 데이터 받고, props로 넘기기 |
| `searchParams` Promise 형태 사용                 | Next.js App Router에서는 동기 객체로 바로 받아 사용 가능                |

이렇게 살짝만 더 신경 쓰면 깔끔하고 버그 없이 데이터를 다룰 수 있어서 추천드립니다! 필요하면 더 깊게 React와 Next.js의 데이터 흐름도 알려드릴게요~ 행복한 개발 되세요! 🚀

Posts