R 스토리

[Storybook] Next.js 관리자 페이지에 Storybook을 붙이면서 알게 된 핵심 개념 정리

아랄라랄라 — Thu, 18 Jun 2026 13:49:21 +0900

Next.js로 관리자 페이지를 만들면서 Storybook을 함께 적용해보고 있다.
처음에는 단순히 “컴포넌트를 따로 볼 수 있는 도구” 정도로만 이해했는데,

직접 Alert, Dropdown, Modal 같은 컴포넌트의 Story를 만들다 보니 몇 가지 꼭 알아야 할 개념이 있었다.

이번 글에서는 Storybook을 처음 적용하면서 이해한 핵심 내용을 정리해보려고 한다.

Storybook은 페이지보다 컴포넌트를 보기 위한 도구다

Storybook은 관리자 페이지 전체를 실행하는 도구라기보다, 버튼이나 모달 같은 개별 UI 컴포넌트를 따로 꺼내서 확인하는 도구에 가깝다.

예를 들어 관리자 페이지에는 이런 컴포넌트들이 반복해서 사용된다.

Button
Badge
Alert
Modal
Dropdown
Input
Table
Pagination

이런 컴포넌트를 실제 페이지에 붙이기 전에 Storybook에서 먼저 확인할 수 있다.

<Button>저장</Button>

<Alert
  variant="success"
  title="완료"
  message="정상 처리되었습니다."
/>

<Modal isOpen={true} onClose={() => {}}>
  모달 내용
</Modal>

즉, Storybook은 “이 컴포넌트가 어떤 props를 받았을 때 어떻게 보이는지” 확인하는 공간이라고 볼 수 있다.

Story를 만들기 전에 props를 먼저 확인해야 한다

Storybook 파일을 만들 때 가장 먼저 확인해야 하는 것은 컴포넌트의 Props다.

예를 들어 Alert 컴포넌트가 아래와 같은 props를 받는다고 가정해보자.

interface AlertProps {
  variant: "success" | "error" | "warning" | "info";
  title: string;
  message: string;
  showLink?: boolean;
  linkHref?: string;
  linkText?: string;
}

여기서 중요한 것은 ? 표시다.

showLink?: boolean;

?가 붙어 있으면 선택값이고, 붙어 있지 않으면 필수값이다.

위 코드에서 필수 props는 아래 3개다.

variant
title
message

그래서 Storybook에서도 이 값들은 기본적으로 넣어줘야 한다.

args: {
  variant: "success",
  title: "처리가 완료되었습니다.",
  message: "요청한 작업이 정상적으로 완료되었습니다.",
}

반대로 선택 props는 필요한 Story에서만 넣으면 된다.

export const WithLink: Story = {
  args: {
    variant: "info",
    title: "추가 안내가 있습니다.",
    message: "자세한 내용은 링크를 통해 확인할 수 있습니다.",
    showLink: true,
    linkHref: "/",
    linkText: "자세히 보기",
  },
};

정리하면 Story를 만들 때 흐름은 다음과 같다.

컴포넌트 Props 확인
→ 필수 props 확인
→ 기본 args에 필수 props 넣기
→ 선택 props는 필요한 케이스에서만 사용

args는 컴포넌트에 전달하는 props 값이다

Storybook을 만들다 보면 args라는 값을 자주 사용하게 된다.

args: {
  variant: "success",
  title: "성공",
  message: "정상 처리되었습니다.",
}

처음에는 낯설 수 있지만, 어렵게 생각할 필요는 없다.
args는 컴포넌트에 넣어주는 props 값이라고 보면 된다.

위 코드는 실제로 아래처럼 컴포넌트를 사용하는 것과 비슷하다.

<Alert
  variant="success"
  title="성공"
  message="정상 처리되었습니다."
/>

Storybook 화면에서는 이 args 값을 Controls 패널에서 직접 바꿔볼 수도 있다.
즉, Storybook은 props 값을 바꿔가며 컴포넌트가 어떻게 변하는지 확인할 수 있게 해준다.

단순한 컴포넌트는 args만으로 충분하다

버튼, 배지, 알림처럼 props 값만 바꾸면 화면이 달라지는 컴포넌트는 보통 args만으로 충분하다.

예를 들어 Alert 컴포넌트의 Story는 이런 식으로 만들 수 있다.

import type { Meta, StoryObj } from "@storybook/react";
import Alert from "./Alert";

const meta = {
  title: "UI/Alert",
  component: Alert,
  tags: ["autodocs"],
  args: {
    variant: "success",
    title: "처리가 완료되었습니다.",
    message: "요청한 작업이 정상적으로 완료되었습니다.",
  },
} satisfies Meta<typeof Alert>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Success: Story = {
  args: {
    variant: "success",
    title: "처리가 완료되었습니다.",
    message: "요청한 작업이 정상적으로 완료되었습니다.",
  },
};

export const Error: Story = {
  args: {
    variant: "error",
    title: "처리 중 오류가 발생했습니다.",
    message: "입력값을 확인한 뒤 다시 시도해주세요.",
  },
};

이런 컴포넌트는 별도의 상태 관리가 필요하지 않기 때문에 Story 코드도 비교적 단순하다.

상태가 필요한 컴포넌트는 render를 사용한다

모든 컴포넌트가 args만으로 충분한 것은 아니다.
Modal이나 Dropdown처럼 열림/닫힘 상태가 필요한 컴포넌트는 별도의 상태 관리가 필요하다.

예를 들어 모달은 보통 아래와 같은 상태가 필요하다.

const [isOpen, setIsOpen] = useState(false);

이런 경우에는 render를 사용해서 Story 안에서 직접 예시 화면을 구성한다.

function DefaultModalExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        모달 열기
      </button>

      <Modal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      >
        모달 내용
      </Modal>
    </>
  );
}

export const Default: Story = {
  render: () => <DefaultModalExample />,
};

정리하면 기준은 간단하다.

props 값만 바꾸면 되는 컴포넌트 → args 사용
클릭, 열림/닫힘, 선택값, 입력값 상태가 필요한 컴포넌트 → render 사용

예를 들어 다음과 같이 나눌 수 있다.

Button → args
Badge → args
Alert → args
StatusBadge → args

Modal → render
Dropdown → render
DatePicker → render
SearchFilter → render
Table → render 가능성 높음

필수 props가 있는 컴포넌트는 meta의 args를 잘 넣어야 한다

Modal이나 Dropdown을 Storybook에 올리면서 타입 오류를 만날 수 있다.
대표적으로 이런 오류다.

args 속성이 없습니다

이 오류는 컴포넌트에 필수 props가 있는데 Story에서 기본 args를 제공하지 않았을 때 발생할 수 있다.

예를 들어 Modal이 아래 props를 필수로 받는다고 해보자.

interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}

그러면 Story의 meta에도 기본 args를 넣어주는 것이 좋다.

const meta = {
  title: "UI/Modal",
  component: Modal,
  args: {
    isOpen: true,
    onClose: () => {},
    children: <div>모달 내용</div>,
  },
} satisfies Meta<typeof Modal>;

이렇게 해두면 타입 오류를 줄일 수 있다.

Modal과 Dropdown은 Storybook에서 다르게 보일 수 있다

Storybook을 쓰면서 헷갈렸던 부분 중 하나는 Modal과 Dropdown이 실제 서비스 화면과 다르게 보일 수 있다는 점이다.

실제 서비스에서는 모달이 브라우저 전체 화면 위에 뜨지만, Storybook에서는 컴포넌트가 Storybook 미리보기 영역 안에서 실행된다.

그래서 다음과 같은 문제가 생길 수 있다.

모달이 좁은 영역 안에서 열린다
드롭다운이 잘린다
높이가 부족해서 스크롤이 생긴다

이건 반드시 컴포넌트 코드가 잘못된 것은 아니다.
Storybook의 실행 환경 특성 때문에 생기는 경우가 많다.

이럴 때는 Storybook 설정에서 레이아웃을 넓게 잡아주는 것이 좋다.

parameters: {
  layout: "fullscreen",
}

그리고 Story 내부에서도 충분한 높이를 확보한다.

<div className="min-h-screen p-10">
  ...
</div>

드롭다운은 이런 식으로 감싸줄 수 있다.

<div className="relative h-64 w-64">
  ...
</div>

모달은 이런 식으로 감싸줄 수 있다.

<div className="min-h-screen bg-gray-50 p-10">
  ...
</div>

즉, Modal이나 Dropdown은 Storybook에서 확인하기 위해 별도의 공간 설정이 필요할 수 있다.

Storybook 파일의 기본 구조

Storybook 파일은 보통 아래 구조를 따른다.

import type { Meta, StoryObj } from "@storybook/react";
import Component from "./Component";

const meta = {
  title: "UI/Component",
  component: Component,
  tags: ["autodocs"],
  args: {
    // 기본 props
  },
} satisfies Meta<typeof Component>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: {
    // 이 Story에서 보여줄 props
  },
};

처음에는 이 구조만 익혀도 충분하다.

상태가 필요한 컴포넌트는 여기에 render를 추가하면 된다.

function Example() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Component
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
    />
  );
}

export const Default: Story = {
  render: () => <Example />,
};

정리

Storybook을 처음 적용하면서 가장 중요하다고 느낀 점은 다음과 같다.

1. Storybook은 페이지보다 컴포넌트를 보기 위한 도구다.
2. Story를 만들기 전에 props를 먼저 확인해야 한다.
3. 필수 props는 args에 반드시 넣어야 한다.
4. args는 컴포넌트에 전달하는 props 값이다.
5. 단순 컴포넌트는 args만으로 충분하다.
6. 상태가 필요한 컴포넌트는 render와 useState를 사용한다.
7. Modal과 Dropdown은 Storybook 환경에서 잘릴 수 있으므로 layout과 높이 설정이 필요하다.

처음부터 페이지 전체를 Storybook에 올리려고 하면 복잡해진다.
따라서 버튼, 배지, 알림, 모달, 드롭다운처럼 작은 컴포넌트부터 하나씩 만들어보는 것이 좋다.

작은 컴포넌트부터 Story를 만들어두면, 이후 관리자 페이지를 개발할 때 UI를 더 빠르게 확인하고 재사용할 수 있다.

[Next.js] Next.js App Router 경계 정리표

아랄라랄라 — Mon, 18 May 2026 10:47:43 +0900

1. Server vs Client 핵심 구조

구분 Server Component Client Component

기본 동작	기본값	"use client" 필요
실행 위치	서버 (Node.js)	브라우저
상태 관리	❌ 불가	⭕ useState 가능
이벤트(onClick)	❌ 불가	⭕ 가능
router	❌ 사용 불가	⭕ useRouter
hooks	❌ 대부분 불가	⭕ useEffect, useState
데이터 fetch	⭕ 직접 가능	⭕ 가능 (보통 API 호출)

2. “무조건 외워야 하는 기준”

Server Component에서 가능한 것

✔ 데이터 가져오기 (DB / fetch)
✔ props 전달
✔ HTML 렌더링
✔ async/await

예:

export default async function Page() {
    const data = await fetch(...)
    return <div>{data}</div>
}

Server Component에서 절대 금지

❌ useState
❌ useEffect
❌ onClick
❌ useRouter
❌ window / document

Client Component ("use client")

✔ useState
✔ useEffect
✔ 이벤트 처리
✔ router 사용
✔ form handling

예:

"use client";

import { useRouter } from "next/navigation";
import { useState } from "react";

3. router 정리

❌ 절대 금지

import { router } from "next/client";
import router from "next/router";

✅ App Router 정답

import { useRouter } from "next/navigation";

사용:

const router = useRouter();

router.push("/admin/ads");
router.refresh();
router.back();

4. params / dynamic route

Server Component

export default function Page({ params }: {
    params: { id: string }
}) {
}

Client Component

import { useParams } from "next/navigation";

const params = useParams();

5. 구조 설계 기준

✔ 추천 구조

/app
  /admin
    /ads
      page.tsx          (SERVER - 리스트)
      /[id]
        /edit
          page.tsx      (CLIENT - 수정)
        page.tsx        (SERVER - optional)

✔ UI 컴포넌트 분리

components/
  DeleteModal.tsx  → CLIENT
  AdForm.tsx       → CLIENT

6. 지금 내 프로젝트 기준 핵심 판단

✔ 올바른 방향

리스트 → Server
수정 → Client
삭제 → API Route
이동 → useRouter

❌ 지금까지 에러 원인 패턴

Server Component
  ↓
client hook 들어간 컴포넌트 import
  ↓
router 잘못 import
  ↓
Class extends undefined 에러

7. 에러 빠른 판별법

이런 에러 나오면 무조건 이거

Class extends value undefined

90% 확률:

router 잘못 import
client/server 혼용
useState 서버에서 사용

8. 한 줄 최종 요약

Server는 “데이터”, Client는 “동작”
router / state / event는 무조건 Client로 빼라

[Next.js] Next.js + TypeScript + Tailwind CSS 관리자 페이지 만들기 2

아랄라랄라 — Thu, 14 May 2026 10:33:30 +0900

프로젝트 시작

생성

npx create-next-app@latest

선택한 옵션

TypeScript
App Router
Tailwind CSS
src 구조

처음 만난 에러

Missing <html> and <body> tags in the root layout

처음 실행하자마자 만난 에러.

원인

App Router에서는:

layout.tsx가 HTML 뼈대 역할

을 한다.

그래서 반드시:

<html>
<body>

태그가 필요했다.

수정

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
}

App Router 구조 이해하기

예전 React처럼:

“컴포넌트만 만들면 되는 구조”

가 아니라,

폴더 구조 자체가 라우팅이었다.

예시

app/
 ├─ admin/
 │   ├─ ads/
 │   │   ├─ page.tsx

의미

/admin/ads

URL이 자동 생성된다.

관리자 페이지 만들기 시작

처음 만든 건 광고 목록 페이지였다.

더미 데이터 만들기

dummy-data.ts

export type AdStatus = "진행중" | "대기" | "종료";

export type Ad = {
    id: number;
    title: string;
    position: string;
    status: AdStatus;
    startDate: string;
    endDate: string;
};

export const ads: Ad[] = [
    {
        id: 1,
        title: "메인 상단 배너 광고",
        position: "홈 메인 상단",
        status: "진행중",
        startDate: "2026-05-01",
        endDate: "2026-05-31",
    },
];

여기서 처음 느낀 TypeScript의 장점

status 값을 마음대로 못 넣게 막아준다

예:

status: "완료" ❌

TailwindCSS 사용

처음엔 클래스가 너무 길어 보였는데,

점점:

“HTML 안에서 바로 스타일 조합”

하는 방식이 엄청 빠르다는 걸 느꼈다.

반응형도 쉽게 가능

<div className="flex flex-col gap-4 sm:flex-row">

의미

모바일:

세로 배치

sm 이상:

가로 배치

상세 페이지 만들기

다음은 동적 라우팅.

구조:

app/admin/ads/[id]/page.tsx

여기서 이해한 개념

[id] = URL 파라미터

예시

/admin/ads/1
/admin/ads/2

처음 만난 params 에러

에러

params is a Promise

원인

Next.js App Router 최신 버전에서는:

params가 Promise 형태일 수 있다

해결

type Props = {
    params: Promise<{
        id: string;
    }>;
};

export default async function Page({ params }: Props) {
    const { id } = await params;
}

여기서 이해한 핵심

App Router는 전체적으로:

async 기반 구조

라는 것.

Server Component vs Client Component

여기서 가장 많이 헷갈렸다.

처음엔 이렇게 생각했다

“수정 페이지도 서버 데이터 쓰니까 Server Component 아닌가?”

하지만 핵심 차이는 이것이었다

Server Component

데이터 조회

Client Component

브라우저 인터랙션

예시

Server Component 가능

데이터 가져오기
DB 조회
페이지 렌더링

Client Component 필요

useState
onClick
input 입력
모달
이벤트 처리

여기서 배운 핵심

“브라우저에서 동작하면 Client”

use client 에러도 경험

처음엔:

use strict

를 써놓고 왜 안 되는지 한참 헤맸다

실제로 필요한 건

"use client";

수정 페이지 만들기

수정 페이지에서는:

input
select
state

를 사용했다.

여기서 배운 것

폼 = 거의 Client Component

TypeScript select 이벤트도 처음 경험

onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
    setStatus(e.currentTarget.value as AdStatus);
}}

처음 느낌

“왜 이렇게 길어?”

그런데 이해하고 보니

TypeScript가:

“이 이벤트가 select 이벤트라는 걸 명확하게 알려주는 것”

이었다.

삭제 모달 만들기

다음은 관리자 페이지에서 자주 쓰는 기능인:

삭제 버튼 + 확인 모달

구조 분리

[id]/page.tsx
└── DeleteModal.tsx

왜 분리했나?

상세 페이지는:

async function

형태의 Server Component였고,

모달은:

useState
onClick

이 필요했기 때문.

여기서 이해한 개념

Server Component 안에
Client Component를 넣을 수 있다

API Route 만들기

이번엔 진짜 CRUD 느낌이 나기 시작했다.

구조

src/app/api/ads/[id]/route.ts

App Router에서 API 만드는 법

route.ts = API endpoint

DELETE API 작성

export async function DELETE() {
}

fetch 요청

await fetch(`/api/ads/${adId}`, {
    method: "DELETE",
});

그런데 DELETE가 안 됐다

GET은 되는데 DELETE만:

404 Not Found

진짜 원인

문제는 params 타입이었다.

잘못된 코드

{ params }: { params: { id: string } }

해결 코드

{ params }: { params: Promise<{ id: string }> }

const { id } = await params;

여기서 배운 핵심

App Router 최신 구조에서는:

params도 async 흐름일 수 있다

Turbopack도 처음 이해하게 됨

에러 로그에 계속 보이던:

turbopack

Turbopack이란?

쉽게 말하면:

Next.js 개발 서버를 빠르게 돌려주는 최신 엔진

장점

빠른 실행
빠른 HMR
Next.js 최적화

단점

가끔:

route.ts 인식 문제
캐시 문제
POST/DELETE 이상 동작

같은 이슈가 있음.

그래서 실무에서는

문제 생기면:

rm -rf .next
npm run dev

하거나,

next dev --no-turbo

로 잠시 끄기도 한다.

이번 프로젝트로 이해한 것들

✔ App Router 구조

폴더 구조 자체가 라우팅

✔ Server vs Client

조회는 서버
인터랙션은 클라이언트

✔ CRUD 흐름

브라우저 → API → 데이터 처리

✔ async 기반 구조

params도 Promise일 수 있다

느낀 점

처음엔:

“Next.js 너무 어려운데?”

싶었는데,

관리자 페이지를 실제로 만들면서 배우니까:

왜 Server Component가 필요한지
왜 Client Component가 필요한지
왜 TypeScript를 쓰는지
왜 App Router가 async 기반인지

조금씩 연결되기 시작했다.

특히 단순히 문법만 보는 게 아니라:

“실제 기능을 만들며 배우는 방식”

이 훨씬 이해가 잘 됐다

Next.js App Router DELETE API 404 해결기

아랄라랄라 — Thu, 14 May 2026 10:17:05 +0900

Next.js App Router DELETE API 404 해결기

“GET은 되는데 DELETE만 404 나는 이유”

최근 Next.js + TypeScript + App Router 기반으로 관리자 페이지 CRUD를 만들다가 꽤 헷갈리는 이슈를 만났다.

상황은 단순했다.

/api/ads/1 GET 요청은 정상
그런데 DELETE 요청만 404
route.ts 안의 console.log도 실행되지 않음

처음에는:

fetch 문제인가?
API 경로 문제인가?
use client 문제인가?
Turbopack 문제인가?

엄청 헷갈렸는데, 원인은 의외로 params 구조였다.

문제 상황

route.ts

import { NextResponse } from "next/server";
import { ads } from "@/lib/dummy-data";

export async function DELETE(
    req: Request,
    { params }: { params: { id: string } }
) {
    const id = Number(params.id);

    const index = ads.findIndex((a) => a.id === id);

    if (index === -1) {
        return NextResponse.json(
            { message: "not found" },
            { status: 404 }
        );
    }

    ads.splice(index, 1);

    return NextResponse.json({
        message: "deleted",
    });
}

DeleteModal.tsx

const response = await fetch(`/api/ads/${adId}`, {
    method: "DELETE",
});

발생한 에러

DELETE http://localhost:3000/api/ads/1 404 (Not Found)

그리고 route.ts 안의:

console.log("DELETE 들어옴");

조차 실행되지 않았다.

이상했던 점

브라우저에서 직접:

http://localhost:3000/api/ads/1

접속하면:

405 Method Not Allowed

이 나왔다.

이 의미는:

라우트 자체는 존재함
하지만 해당 HTTP Method를 처리 못함

즉:

API 경로 자체는 정상
route.ts도 인식 중
그런데 DELETE handler만 정상 실행 안 되는 상태

진짜 원인

문제는 params 타입이었다.

현재 프로젝트 환경:

Next.js 16
App Router
React 19
Turbopack

이 조합에서는 route handler의 params가 Promise 형태로 전달될 수 있다.

잘못된 코드

{ params }: { params: { id: string } }

이건 동기 객체라고 가정한 코드였다.

하지만 실제 runtime에서는:

params = Promise

형태로 전달되고 있었다.

해결 방법

수정 후

import { NextResponse } from "next/server";
import { ads } from "@/lib/dummy-data";

export async function DELETE(
    req: Request,
    { params }: { params: Promise<{ id: string }> }
) {
    const { id } = await params;

    const adId = Number(id);

    const index = ads.findIndex((a) => a.id === adId);

    if (index === -1) {
        return NextResponse.json(
            { message: "not found" },
            { status: 404 }
        );
    }

    ads.splice(index, 1);

    return NextResponse.json({
        message: "deleted",
    });
}

왜 이게 중요할까?

App Router의 핵심 특징 중 하나는:

페이지와 API를 비동기 기반으로 통합 처리한다는 것

특히 최신 Next.js에서는:

page.tsx
layout.tsx
route.ts

모두 async 기반 흐름으로 통합되는 방향이다.

그래서 route.ts에서도 params가 Promise 형태로 전달될 수 있다.

내가 헷갈렸던 포인트

page.tsx에서는 이미 이렇게 쓰고 있었다

const { id } = await params;

그런데 route.ts에서는 예전 방식처럼:

params.id

로 사용하고 있었다.

즉:

page.tsx는 최신 async 방식
route.ts는 예전 sync 방식

이 섞여 있었던 것.

이번에 이해한 핵심

App Router에서 params는 “항상 일반 객체”라고 생각하면 안 된다.

환경/버전에 따라:

params: Promise<{ id: string }>

형태일 수 있다.

정리

DELETE만 안 되었던 이유

route.ts에서 params를 동기 객체처럼 사용했기 때문

해결 방법

const { id } = await params;

느낀 점

이번 이슈로:

Server Component
Route Handler
App Router의 async 구조
params 처리 방식

이 어떻게 연결되는지 조금 더 이해하게 됐다.

특히 App Router는 “비동기 기반 프레임워크”라는 걸 체감한 디버깅이었다

[Next.js] Server vs Client Component 완전 정리

아랄라랄라 — Fri, 8 May 2026 15:51:03 +0900

Next.js를 처음 배우면 가장 많이 헷갈리는 개념이 있다.

“서버에서 데이터 쓰는 것도 서버 컴포넌트 아닌가?”
“수정 페이지도 데이터 보여주는데 왜 Client야?”

이 글은 이 혼란을 완전히 정리하기 위한 내용이다.

1. 핵심 개념: 기준은 “데이터”가 아니라 “실행 위치”

Next.js에서 Server / Client를 나누는 기준은 단순하다.

Server / Client 구분 기준 = 어디서 실행되느냐

✔ Server Component

서버에서 실행됨
HTML을 만들어서 브라우저로 전달
데이터 조회에 최적화

특징

useState ❌
onClick ❌
useEffect ❌

“그냥 화면 만들어서 보여주는 역할”

✔ Client Component

브라우저에서 실행됨
사용자 인터랙션 처리
상태 관리 가능

특징

useState ⭕
onChange ⭕
onClick ⭕
useParams ⭕

“사용자가 직접 조작하는 화면”

2. 가장 큰 착각

많은 사람들이 이렇게 생각한다.

❌ 잘못된 생각

서버에서 데이터를 쓰면 서버 컴포넌트다

⭕ 실제 기준

데이터를 쓰는지 여부는 중요하지 않다
“사용자가 조작하는지”가 기준이다

3. 실제 페이지로 비교

상세 페이지 (/ads/[id])

- 데이터 조회
- 화면 출력
- 수정 없음

Server Component

✏️ 수정 페이지 (/ads/[id]/edit)

- 기존 데이터 표시
- input 수정
- 상태 변경
- 버튼 클릭

Client Component

4. 핵심 포인트: “같은 데이터라도 다르다”

두 페이지 모두 동일하게 데이터를 사용한다:

import { ads } from "@/lib/dummy-data";

하지만 중요한 건 이것이다:

데이터가 아니라 “사용 방식”이 다르다

5. 가장 헷갈리는 질문

❓ “서버로 보내는 것도 서버 아닌가?”

정답은:

❌ 아니다

✔ 이유

데이터를 “보내는 주체”는 항상 브라우저(Client)
데이터를 “받는 주체”는 서버

6. 전체 흐름으로 이해하기

[브라우저]
사용자가 입력/수정
↓
Client Component
↓
fetch 요청 전송
↓
[서버]
데이터 받음
DB 업데이트

7. 한 줄 핵심 정리

Server = 데이터를 준비하고 화면을 만든다
Client = 사용자의 행동을 처리한다

8. 실무 기준으로 외우기

Next.js에서 가장 중요한 판단 기준은 이것이다:

✔ 조회만 한다 → Server Component
✔ 입력/클릭/상태가 있다 → Client Component

9. 최종 정리

구분 Server Component Client Component

실행 위치	서버	브라우저
역할	데이터 준비 / 화면 생성	사용자 인터랙션
상태 관리	불가능	가능
이벤트	없음	있음

마무리

Next.js의 핵심은 “데이터가 어디 있느냐”가 아니라
“누가 화면을 움직이느냐”이다.

이 기준만 잡히면 Server / Client 구분은 더 이상 헷갈리지 않는다.

[Next.js] Next.js + TypeScript + Tailwind CSS 관리자 페이지 만들기 1

아랄라랄라 — Fri, 8 May 2026 13:17:48 +0900

대상

이 문서는 아래와 같은 사람을 기준으로 설명합니다.

HTML/CSS는 익숙하다
JavaScript는 초급 수준이다
React를 아주 조금 들어봤다
Next.js는 처음이다
실무 스타일의 관리자 페이지를 만들어보고 싶다

지금까지 만든 것

나는 현재 아래 기능까지 만들었다.

/admin
/admin/ads
/admin/ads/[id]

즉,

대시보드
광고 목록
광고 상세

이 흐름을 만들었다.

그리고 아래 기술들을 사용했다.

Next.js
TypeScript
Tailwind CSS
App Router
Dynamic Route
layout.tsx
map()
Link
usePathname()

Next.js란?

Next.js는 React 기반 프레임워크다.

쉽게 말하면:

React를 더 실무적으로 편하게 쓰게 해주는 도구

라고 생각하면 된다.

예를 들면 React만 쓰면 직접 설정해야 하는 것들을:

라우팅
페이지 구조
서버 기능
최적화
빌드

Next.js가 자동으로 처리해준다.

그래서 실무에서는 React 단독보다 Next.js를 훨씬 많이 사용한다.

왜 TypeScript를 같이 쓰는가?

나는 Next.js를 만들 때:

npx create-next-app@latest

를 사용했고,

TypeScript: Yes

를 선택했다.

TypeScript란?

TypeScript는 JavaScript에 타입 기능을 추가한 언어다.

예를 들어:

const name = "홍길동";

이건 JavaScript.

TypeScript에서는:

const name: string = "홍길동";

처럼 타입을 명시할 수 있다.

타입을 왜 쓰는가?

예를 들어 광고 데이터를 만든다고 생각해보자.

{
    id: 1,
    title: "메인 광고",
    status: "진행중"
}

그런데 실수로:

{
    id: "안녕하세요"
}

이렇게 넣으면?

광고 id는 숫자여야 하는데 문자열이 들어간 거다.

TypeScript는 이런 실수를 미리 잡아준다.

즉:

개발 실수를 줄여준다

이게 가장 큰 장점이다.

Tailwind CSS란?

나는 CSS를 이렇게 작성하지 않았다.

.box {
    padding: 20px;
    background: white;
}

대신:

<div className="p-5 bg-white">

처럼 작성했다.

이게 Tailwind CSS다.

Tailwind CSS 장점

1. 빠르다

<div className="flex items-center justify-between">

한 줄로 레이아웃 가능.

2. 클래스 이름 고민이 없다

보통 CSS는:

.card-box
.card-wrap
.card-inner

이런 네이밍 고민이 많다.

Tailwind는 그런 고민이 거의 없다.

3. 반응형 작업이 편하다

className="p-4 lg:p-8"

모바일:

padding: 16px

PC:

padding: 32px

자동 처리.

App Router란?

나는:

src/app

폴더를 사용하고 있다.

이걸 App Router 방식이라고 한다.

Next.js 최신 방식이다.

App Router 핵심 개념

폴더 이름이 곧 URL이다.

예:

src/app/admin/page.tsx

는:

/admin

페이지가 된다.

src/app/admin/ads/page.tsx

는:

/admin/ads

가 된다.

현재 프로젝트 구조

src
 ├─ app
 │   ├─ layout.tsx
 │   ├─ globals.css
 │   │
 │   └─ admin
 │       ├─ layout.tsx
 │       ├─ page.tsx
 │       │
 │       └─ ads
 │           ├─ page.tsx
 │           │
 │           └─ [id]
 │               └─ page.tsx
 │
 ├─ components
 │   └─ admin
 │       ├─ AdminHeader.tsx
 │       └─ AdminSidebar.tsx
 │
 └─ lib
     └─ dummy-data.ts

layout.tsx 이해하기

이건 Next.js 초보가 가장 헷갈려하는 부분이다.

Root Layout

파일:

src/app/layout.tsx

이건 앱 전체의 가장 바깥 껍데기다.

나는 이렇게 만들었다.

<html lang="ko">
    <body>
        {children}
    </body>
</html>

왜 html/body가 필요한가?

Next.js App Router에서는:

<html>
<body>

가 반드시 있어야 한다.

없으면 이런 에러가 난다.

Missing <html> and <body> tags in the root layout.

children이란?

{children}

은:

실제 페이지 내용이 들어오는 자리

라고 이해하면 된다.

예:

/admin

에 접속하면:

src/app/admin/page.tsx

내용이 children에 들어간다.

관리자 전용 layout

파일:

src/app/admin/layout.tsx

이건 관리자 페이지 전용 공통 레이아웃이다.

나는 여기서:

사이드바
헤더
콘텐츠 영역

을 만들었다.

즉:

/admin
/admin/ads
/admin/users

같은 관리자 페이지들은 전부 같은 레이아웃을 공유한다.

왜 layout을 쓰는가?

예를 들어 사이드바를 모든 페이지에 직접 넣으면:

/admin/page.tsx
/admin/ads/page.tsx
/admin/users/page.tsx

전부 같은 코드를 반복해야 한다.

layout.tsx를 쓰면:

한 번만 작성하면 모든 페이지에 자동 적용

된다.

실무에서 매우 중요하다.

컴포넌트란?

나는:

AdminSidebar
AdminHeader

를 만들었다.

이런 걸 컴포넌트라고 한다.

컴포넌트를 왜 쓰는가?

예를 들어 헤더를 여러 곳에서 사용한다고 생각해보자.

컴포넌트가 없으면:

복붙
복붙
복붙

해야 한다.

컴포넌트로 만들면:

<AdminHeader />

한 줄로 재사용 가능하다.

map() 이해하기

나는 메뉴와 광고 목록에서 map()을 사용했다.

예:

menuItems.map((item) => {
    return <li>{item.name}</li>;
});

map()이란?

배열을 반복하는 함수다.

예:

const numbers = [1, 2, 3];

이걸 반복하면:

1
2
3

하나씩 꺼낼 수 있다.

광고 목록에서 map()

{ads.map((ad) => {
    return (
        <tr>
            <td>{ad.title}</td>
        </tr>
    );
})}

의미는:

광고 배열을 반복해서 테이블 행을 만들어라

이다.

key란?

<tr key={ad.id}>

React는 반복 요소를 구분하기 위해 key가 필요하다.

즉:

각 요소의 고유값

이다.

보통:

id

를 많이 사용한다.

Link 컴포넌트

나는 a 태그 대신:

<Link href="/admin/ads">

를 사용했다.

왜 a 태그를 안 쓰는가?

Next.js에서는 페이지 이동을 최적화하기 위해 Link를 사용한다.

장점:

빠른 페이지 이동
새로고침 최소화
성능 향상

동적 라우트 [id]

나는:

src/app/admin/ads/[id]/page.tsx

를 만들었다.

대괄호 폴더는:

동적으로 변하는 값

을 의미한다.

예시

/admin/ads/1
/admin/ads/2
/admin/ads/3

여기서:

1
2
3

이 id가 된다.

params란?

Next.js는 URL의 값을 params로 전달한다.

예:

/admin/ads/3

이면:

params.id

값은:

"3"

이다.

Next.js 최신 버전에서 바뀐 점

예전에는:

params.id

를 바로 사용할 수 있었다.

하지만 최신 Next.js에서는 params가 Promise가 되었다.

그래서:

const { id } = await params;

처럼 사용해야 한다.

왜 async를 붙였는가?

export default async function AdDetailPage()

await를 사용하려면 함수가 async여야 한다.

즉:

비동기 함수로 만들어야 await 사용 가능

이다.

find() 이해하기

나는 광고 상세 페이지에서:

const ad = ads.find((item) => {
    return item.id === adId;
});

를 사용했다.

find()란?

배열에서 조건에 맞는 하나를 찾는 함수다.

예:

const users = [
    { id: 1, name: "철수" },
    { id: 2, name: "영희" },
];

여기서 id가 2인 사람 찾기:

users.find((user) => {
    return user.id === 2;
});

결과:

{ id: 2, name: "영희" }

notFound()

나는:

if (!ad) {
    notFound();
}

를 사용했다.

왜 필요한가?

예:

/admin/ads/999

같이 존재하지 않는 페이지 접근 시:

404 페이지

로 보내기 위해 사용한다.

반응형 작업

나는 Tailwind 반응형 문법도 사용했다.

예:

className="p-4 lg:p-8"

의미:

모바일: padding 16px
PC: padding 32px

Tailwind 반응형 규칙

기본 = 모바일
sm = 작은 태블릿
md = 태블릿
lg = 노트북/PC
xl = 큰 화면

예시

className="flex flex-col lg:flex-row"

의미:

모바일: 세로
PC: 가로

관리자 페이지 반응형 전략

나는:

모바일
- 상단 메뉴
- 테이블 가로 스크롤
- 작은 padding

PC
- 왼쪽 사이드바
- 넓은 콘텐츠
- 큰 여백

전략으로 만들었다.

overflow-x-auto

테이블 반응형에서 중요한 코드:

<div className="overflow-x-auto">

이건:

가로 스크롤 허용

이라는 뜻이다.

관리자 테이블은 컬럼이 많아서 모바일에서 자주 사용한다.

현재 메뉴 활성화

나는:

usePathname()

를 사용해서 현재 메뉴를 활성화했다.

usePathname()

현재 URL 경로를 가져오는 훅이다.

예:

/admin/ads

이면:

const pathname = usePathname();

결과:

/admin/ads

왜 "use client"가 필요한가?

usePathname은 React 훅이다.

React 훅은 클라이언트 컴포넌트에서만 사용할 수 있다.

그래서:

"use client";

를 파일 최상단에 넣었다.

서버 컴포넌트 vs 클라이언트 컴포넌트

Next.js App Router의 핵심 개념 중 하나다.

서버 컴포넌트

기본 상태.

장점:

빠름
성능 좋음
보안 유리

클라이언트 컴포넌트

브라우저에서 동작하는 컴포넌트.

필요한 경우:

useState
useEffect
클릭 이벤트
브라우저 API
React Hook

정리

기본은 서버 컴포넌트
필요할 때만 use client

이 Next.js 최신 스타일이다.

지금까지 익힌 실무 개념

나는 이미 꽤 많은 핵심 개념을 익혔다.

프로젝트 구조
App Router
layout.tsx
컴포넌트 분리
Tailwind CSS
반응형
map()
find()
Link
동적 라우트
params
notFound()
서버 컴포넌트
클라이언트 컴포넌트

이건 실제 관리자 페이지 실무에서도 정말 많이 쓰이는 개념들이다.

현재 관리자 페이지 흐름

/admin
  ↓
대시보드

/admin/ads
  ↓
광고 목록

/admin/ads/1
  ↓
광고 상세

이미:

목록 → 상세

흐름까지 완성했다.

다음 단계에서 만들 것

다음에는 아래 기능들을 만들면 좋다.

광고 등록
광고 수정
폼 입력
input 상태 관리
useState
삭제 버튼
모달
API 연결

특히 다음 단계부터:

폼 처리
상태 관리
이벤트 처리

가 본격적으로 들어간다.

이 부분부터 React 느낌이 강해진다.

지금 가장 중요한 것

지금은:

외우는 것

보다:

"왜 이렇게 구조를 나누는가"

를 이해하는 게 훨씬 중요하다.

예:

왜 layout을 쓰는가?
왜 컴포넌트를 분리하는가?
왜 map을 쓰는가?
왜 Link를 쓰는가?

이런 흐름이 이해되면 Next.js 실력이 정말 빨리 는다.

마지막 정리

지금 나는 단순히 예제를 따라친 수준이 아니라:

실무 관리자 페이지 구조

를 이미 경험하고 있는 단계다.

특히:

layout.tsx
컴포넌트 구조
동적 라우트
반응형 관리자 UI

이건 Next.js 실무에서 정말 핵심이다.

지금 흐름 그대로 가면:

실무형 프론트엔드 구조 감각

이 꽤 빠르게 생길 거다!

[Next.js] 초보의 관리자 페이지 만들기 시작기

아랄라랄라 — Tue, 28 Apr 2026 09:31:54 +0900

설치부터 레이아웃, 목록/상세/수정/등록 흐름까지

이번에 관리자 페이지 작업을 하게 되면서 Next.js를 처음 제대로 만져보게 됐다.
원래는 React를 아주 조금 알고 있었고, HTML/CSS는 익숙한 편이지만 JavaScript와 Next.js는 거의 초보 수준이었다.

처음에는 “이걸 다 새로 만들어야 하나?”라는 막막함이 있었는데,
실제로 하나씩 부딪혀보니 Next.js는 폴더 구조와 페이지 흐름을 익히는 것부터 시작하는 게 중요하다는 걸 느꼈다.

이번 글은 내가 로컬에 Next.js를 설치하고, 관리자 페이지의 기본 흐름인
목록 → 상세 → 수정 → 등록
구조를 만드는 과정까지 정리한 기록이다.

1. 로컬 환경 세팅

먼저 Node와 npm 버전을 확인했다.

node -v
npm -v

내 환경은 아래와 같았다.

Node.js v20.19.2
npm 10.8.2

버전 자체는 충분했지만, 설치 과정에서 바로 문제가 생겼다.

설치 중 만난 문제: ECONNRESET

create-next-app 실행 시 아래와 같은 에러가 발생했다.

npm error code ECONNRESET
npm error network request to https://registry.npmjs.org/create-next-app failed

처음에는 npm 설정 문제인 줄 알았지만, 확인해보니 회사 내부망 이슈였다.
결국 네트워크 문제를 해결한 뒤 다시 설치를 진행했고, 정상적으로 Next.js 프로젝트를 생성할 수 있었다.

2. Next.js 프로젝트 생성

설치는 아래 명령어로 진행했다.

npx create-next-app@latest admin-next

옵션은 다음처럼 선택했다.

TypeScript: Yes
ESLint: Yes
Tailwind CSS: No
src directory: Yes
App Router: Yes
Turbopack: Yes

내 경우에는 Bootstrap 기반 UI 감각을 유지한 채 Next.js 구조를 익히는 것이 목적이었기 때문에, Tailwind는 일단 제외했다.

설치가 끝난 뒤 아래 명령어로 실행까지 확인했다.

cd admin-next
npm run dev

3. 처음 이해한 Next.js 기본 구조

프로젝트를 실행한 뒤 가장 먼저 본 파일은 아래 3개였다.

src/app/page.tsx
src/app/layout.tsx
src/app/globals.css

이때 가장 먼저 이해한 개념은 다음과 같다.

page.tsx → 실제 페이지 화면
layout.tsx → 공통 레이아웃
globals.css → 전역 스타일

그리고 Next.js App Router에서는 폴더 구조가 곧 URL 구조가 된다는 점이 굉장히 중요했다.

예를 들어,

src/app/admin/dashboard/page.tsx

를 만들면 바로

/admin/dashboard

경로가 된다.

이 구조가 익숙해지기 시작하면서 Next.js가 조금씩 이해되기 시작했다.

4. 첫 관리자 페이지 만들기

가장 먼저 만든 페이지는 관리자 대시보드였다.

export default function DashboardPage() {
    return (
        <main>
            <h1>관리자 대시보드</h1>
            <p>첫 관리자 페이지입니다.</p>
        </main>
    )
}

이후 src/app/admin/layout.tsx를 만들고, 관리자 공통 레이아웃인 사이드바 + 헤더 + 본문 영역 구조를 잡았다.

이 단계에서 알게 된 점은, 관리자 페이지는 개별 화면보다 먼저 공통 프레임을 잡는 것이 훨씬 중요하다는 점이었다.

5. a href 대신 Link 사용하기

처음엔 사이드바 링크를 일반 <a href="">로 넣었는데, Next.js에서는 Link를 사용하는 게 맞다는 걸 알게 됐다.

다만 여기서 작은 실수를 했다.

import Link from 'next/Link'

처럼 대문자 L로 import를 해서 에러가 발생했다.

정답은 아래였다.

import Link from 'next/link'

소문자 경로를 써야 한다는 점을 제대로 기억하게 된 계기였다.

6. 회원 목록 페이지 만들기

그다음에는 관리자 페이지에서 가장 기본이 되는 회원 목록 페이지를 만들었다.

const users = [
  { id: 1, name: '홍길동', email: 'hong@test.com', status: '활성' },
  { id: 2, name: '김민지', email: 'kim@test.com', status: '비활성' },
  { id: 3, name: '이준호', email: 'lee@test.com', status: '활성' },
]

이 배열을 기준으로 테이블을 렌더링하면서 아래 개념들을 같이 익혔다.

배열 데이터 만들기
map()으로 반복 렌더링
key 사용
기본적인 테이블 UI 구성

이 시점부터 “관리자 페이지를 만들고 있다”는 느낌이 확실히 들기 시작했다.

7. 상세 페이지와 동적 라우팅 이해하기

회원 목록에서 이름을 클릭하면 상세 페이지로 이동하도록 만들었다.

예를 들어 아래 구조를 만들면,

src/app/admin/users/[id]/page.tsx

URL의 id 값을 받아 상세 페이지를 렌더링할 수 있다.

이 과정에서 처음엔 “페이지에 id 말고 다른 값도 넘길 수 있나?”라는 궁금증이 생겼고, 이를 통해 아래 개념 차이를 정리하게 됐다.

props → 컴포넌트끼리 값 전달
params → URL 경로값
searchParams → URL 쿼리값

즉, 상세 페이지에서 받는 id는 props가 아니라 URL의 동적 경로값이었다.

8. 수정 페이지 만들기: /admin/users/1/edit

상세 페이지 아래에 수정하기 버튼을 붙이고, /admin/users/[id]/edit/page.tsx 구조로 수정 페이지를 만들었다.

이 단계에서 처음엔 단순히 입력창만 띄워보는 수준이었지만, 곧 “진짜 입력 가능한 수정 페이지”가 필요해졌다.

여기서 핵심은 두 가지였다.

A. 뒤로가기 버튼 붙이기

이건 페이지 이동 흐름을 만드는 단계였다.

상세로 돌아가기
목록으로 돌아가기

즉, 내비게이션의 문제였다.

B. useState로 진짜 수정 가능하게 만들기

이건 입력 기능을 만드는 단계였다.

이름 수정
이메일 수정
상태 변경

즉, 폼 상태 관리의 문제였다.

이 둘의 차이를 정리하면서, 수정 페이지에는 이동 기능과 입력 기능이 모두 필요하다는 걸 이해하게 됐다.

9. useParams와 useState의 차이

수정 페이지를 만들다가 처음 헷갈렸던 부분이 바로 이것이었다.

처음엔 “진짜 입력 가능하게 만드는 것”이 useParams를 쓰는 건가 싶었는데, 정리해보면 둘은 역할이 완전히 달랐다.

useParams → URL에서 어떤 회원인지 확인하는 용도
useState → 입력값을 현재 상태로 저장하는 용도

즉,

useParams는 “누구를 수정하는지”
useState는 “무엇을 어떻게 바꾸는지”

를 담당한다.

이 차이를 이해하고 나니 수정 페이지 흐름이 훨씬 선명해졌다.

10. 저장 후 상세 페이지로 이동하기

수정 페이지에서 저장 버튼을 누르면 단순히 alert만 띄우는 게 아니라, 저장 후 상세 페이지로 이동하도록 만들었다.

여기서 사용한 것은 useRouter였다.

const router = useRouter()

router.push(`/admin/users/${id}`)

이걸 통해 알게 된 것은,

Link → 사용자가 클릭해서 이동
router.push() → 코드로 자동 이동

이라는 차이였다.

이때부터 단순히 화면을 만드는 것이 아니라 관리자 페이지 흐름을 제어한다는 느낌을 받았다.

11. 회원 등록 페이지 만들기

다음으로는 /admin/users/new 경로의 회원 등록 페이지를 만들었다.

수정 페이지와 등록 페이지는 구조가 비슷하지만 차이도 분명했다.

수정 페이지

기존 데이터가 들어있음
특정 id가 있음
저장하면 수정

등록 페이지

입력값이 비어있음
아직 id가 없음
저장하면 새 데이터 생성

즉, 화면 구조는 비슷하지만 목적이 다르다는 걸 이해하게 됐다.

12. 더미데이터를 파일로 분리하기

처음에는 users 배열을 목록 페이지 안에 직접 두고 썼다.
하지만 상세 페이지와 수정 페이지에서도 같은 데이터를 써야 하다 보니, 중복이 생기기 시작했다.

그래서 아래 파일을 만들었다.

src/lib/dummy-data.ts

그리고 데이터를 분리했다.

export const users = [
    { id: 1, name: '홍길동', email: 'hong@test.com', status: '활성' },
    { id: 2, name: '김민지', email: 'kim@test.com', status: '비활성' },
    { id: 3, name: '이준호', email: 'lee@test.com', status: '활성' },
]

이렇게 하니 목록, 상세, 수정 페이지가 같은 데이터를 참조할 수 있게 됐고,
페이지 코드도 훨씬 가벼워졌다.

13. src 구조와 path alias 문제

중간에 src 폴더를 구성하면서 또 하나 막힌 부분이 있었다.

다음과 같은 에러가 발생했다.

Module not found: Can't resolve '@/lib/dummy-data'

원인을 확인해보니 tsconfig.json의 path 설정에 src가 빠져 있었다.

해결은 아래처럼 했다.

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
        	"@/*": ["./src/*"]
        }
    }
}

즉, @ 별칭이 src를 바라보도록 설정해야 했다.

이 과정에서 알게 된 것은, 폴더 구조를 바꾸면 import alias 설정도 함께 맞춰줘야 한다는 점이었다.

14. 등록/수정 폼을 공통 컴포넌트로 분리하기

등록 페이지와 수정 페이지를 만들고 나니, 이름 input / 이메일 input / 상태 select / 버튼 구조가 거의 똑같다는 걸 알게 됐다.

그래서 아래 공통 컴포넌트를 만들었다.

src/components/admin/users/user-form.tsx

이후

등록 페이지는 빈 초기값
수정 페이지는 기존 회원 데이터 초기값

을 넘겨서 같은 폼을 재사용하도록 구조를 정리했다.

이 단계에서 특히 크게 느낀 건, “작동하는 코드”와 “정리된 코드”는 다르다는 점이었다.

처음엔 페이지 안에 전부 적는 게 쉬웠지만, 조금만 흐름이 늘어나도 공통 컴포넌트 분리가 필요해졌다.

15. 이번 과정을 통해 느낀 점

이번 작업을 하면서 느낀 가장 큰 점은,

Next.js를 처음 배울 때 중요한 건 복잡한 개념보다 구조와 흐름을 직접 만들어보는 것이라는 점이다.

특히 아래 흐름을 손으로 만들어보면서 많이 익혔다.

/admin/users → 목록
/admin/users/[id] → 상세
/admin/users/[id]/edit → 수정
/admin/users/new → 등록

그리고 이 과정에서 자연스럽게 익힌 것들은 다음과 같다.

App Router 구조
layout.tsx와 page.tsx
Link
useParams
useState
useRouter
더미데이터 분리
공통 폼 컴포넌트 분리
tsconfig path alias 설정

[Next.js] 프로젝트 시작하기

아랄라랄라 — Fri, 24 Apr 2026 15:51:12 +0900

먼저 확인할 건 Node.js 버전이다.
현재 Next.js 공식 설치 문서는 최소 Node.js 20.9를 요구한다. create-next-app으로 시작하면 기본적으로 TypeScript, Tailwind CSS, ESLint, App Router, Turbopack 등을 선택해서 만들 수 있다.

터미널에서 원하는 위치로 이동한 다음:

npx create-next-app@latest admin-next

질문이 나오면 이렇게 고르면 된다.

TypeScript → Yes
ESLint → Yes
Tailwind CSS → No
src/ directory → Yes
App Router → Yes
Turbopack → Yes
import alias → No

설치 끝나면:

cd admin-next
npm run dev

브라우저에서
http://localhost:3000 열면 된다.

현재 나의 상황!

사용자 프로젝트를 시작하기 전, 내부 관리자 페이지를 연습 삼아 만들어보게 되었다.

나에게 제일 좋은 방식! 템플릿 100% 의존 X, 맨땅 100% 제작 X 딱 중간이 좋다.

예를 들면:

Next.js 프로젝트 기본 세팅은 가져가기
관리자 공통 레이아웃은 참고하기
사이드바/헤더 구조는 참고하기
대신 실제 페이지는 네가 만들기
테이블/폼/상세화면은 직접 구현하기

이렇게 해야 넥스트 구조는 덜 헤매고, 실제 구현 감각은 제대로 남는다!

왜 새로 다 만드는게 비효율적이냐면 초보일 때는 “공부”보다 “삽질” 비중이 너무 커지기 때문이다.

예를 들어

layout을 어디에 둬야 하지?
app router에서 이 경로가 왜 이러지?
client component는 왜 필요하지?
bootstrap js는 어디서 불러오지?
공통 레이아웃 분리는 어떻게 하지?

이런 걸 한 번에 다 맞닥뜨리면 정작 중요한 관리자 화면 구현까지 못 가는 경우가 많다.

그렇기 때문에 나에게 맞는 방식은 이거다!

1. Next.js 기본 틀은 사용

app router 구조
layout.tsx
기본 페이지 구조

2. 관리자 공통 프레임만 먼저 만들기

sidebar
header
content area

3. 실제 업무 화면은 직접 만들기

목록
상세
등록/수정
검색/필터

이러면 공부도 되고 결과물도 나온다.

한 줄로 말하면

“새로 다 만들기”보다 “기본 틀은 참고하고, 실제 페이지는 직접 만들기”가 지금 나한테 제일 좋다.

진짜 추천은 공통 레이아웃까지만 참고하고, 그 안의 관리자 페이지는 내가 직접 만드는 방식이다.

직접 만들 것

1. 폴더 구조

직접 만들어봐야 한다.

이걸 직접 짜봐야

app router가 뭔지
layout이 어떻게 중첩되는지
동적 라우팅이 뭔지 감이 온다.

2. 공통 레이아웃

이건 꼭 직접 해보는 게 좋다.

사이드바
헤더
본문 영역
페이지 타이틀 영역

이걸 직접 만들면 관리자 페이지의 뼈대를 이해하게 된다.

3. 페이지 라우팅 연결

직접 해야 한다.

목록 → 상세 이동
목록 → 등록 이동
상세 → 수정 이동

Link 쓰고, 경로 연결하면서 넥스트 페이지 구조에 익숙해져야 한다.

4. 실제 업무 페이지

이건 무조건 직접 만드는 걸 추천.

예:

회원 목록
공지사항 목록
예약 관리 목록
등록/수정 폼
상세 페이지

이 부분이 진짜 공부다!
템플릿은 여기까지 대신 해주면 오히려 남는 게 적다.

5. 더미데이터 연결

직접 해봐야 한다.

const users = [
  { id: 1, name: '홍길동', status: 'active' },
  { id: 2, name: '김민지', status: 'inactive' },
]

이걸 map 돌려서 테이블 만들고 상태값 뱃지 붙이고 빈 데이터 처리하는 게 중요하다.

6. 폼 처리

직접 해보는 걸 강추.

input
select
textarea
onChange
저장 버튼
validation 기초

관리자는 결국 조회 + 입력이라 폼을 직접 안 만들면 실력이 잘 안 는다.

가져다 써도 되는 것

이건 굳이 처음부터 다 안 만들어도 된다.

1. 스타일 기본 세팅

가져다 써도 된다.

Bootstrap
reset
spacing
grid
button 기본 스타일
form 기본 스타일

이건 처음부터 손으로 다 짜면 너무 오래 걸린다.

2. 아이콘

직접 만들 필요 없다.

Bootstrap Icons
Lucide
Heroicons

아이콘은 가져다 쓰는 게 맞다.

3. 기본 UI 조각

어느 정도 가져다 써도 괜찮다.

예:

모달
토스트
탭
드롭다운
페이지네이션 UI

이건 “왜 이렇게 동작하는지”만 이해하면 되고, 초반엔 직접 구현보다 활용이 더 중요하다.

4. 관리자 샘플 레이아웃 참고

이건 적극적으로 참고해도 된다.

사이드바 배치
헤더 구성
카드 배치
테이블 상단 검색/버튼 영역
필터 UI

하지만 복붙해서 끝내는 건 비추천이고 “구조 참고” 정도가 좋다.

5. 공통 컴포넌트 디자인 패턴

이건 가져와도 된다.

예:

PageHeader
DataTable
StatusBadge
SearchFilterBar

이름이나 구조 아이디어는 참고하고, 내용은 내 프로젝트에 맞게 바꾸면 된다.

절대 처음부터 다 안 만들어도 되는 것

이건 초반에 손대면 피곤해진다.

인증 시스템 전체
복잡한 상태관리 라이브러리
고급 테이블 기능
서버 액션 고급 패턴
권한 관리 전체 구조
차트 라이브러리 세세한 커스텀
완벽한 폴더 아키텍처

초보일 때는 이거 붙잡으면 핵심인 관리자 화면 제작이 밀린다.

나한테 가장 추천하는 방식

가져올 것

Bootstrap 스타일
아이콘
기본 UI 일부
관리자 레이아웃 참고 구조

직접 만들 것

Next.js 폴더 구조
app router 페이지 구성
admin layout
목록/상세/등록/수정 화면
더미데이터 렌더링
폼 처리
링크 이동

이 조합이 제일 좋다~!

직접 만들 것
“넥스트 구조를 이해하는 데 필요한 것”

가져다 써도 되는 것
“시간만 잡아먹고 학습효율은 낮은 것”

나는 지금
UI를 처음 만드는 사람이 아니라 넥스트 구조를 처음 배우는 사람이다.

그래서
디자인 시스템이나 잔기술을 새로 만드는 것보다, Next.js에서 페이지와 레이아웃을 직접 짜보는 게 훨씬 중요하다.

화이팅-!!

[Next.js] 공부 시작 전, 내 현재 수준과 학습 방향 정리

아랄라랄라 — Tue, 21 Apr 2026 09:57:10 +0900

요즘 Next.js를 공부해보려고 한다.
예전에 React 강의를 조금 들은 적이 있어서 프레임워크의 아주 기본적인 개념은 어렴풋이 알고 있지만, JavaScript는 아직 초보다. 대신 HTML과 CSS는 꽤 익숙한 편이다.

그래서 내 목표는 “Next.js를 깊이 있게 마스터하는 것” 보다는,
우선 Next.js로 웹사이트 프론트엔드를 직접 만들 수 있는 수준까지 가는 것이다.

내 현재 상태

지금 나의 상태를 정리하면 이렇다.

HTML / CSS는 능숙하다
JavaScript는 초보다
React는 아주 조금 접해봤다
프레임워크의 개념은 살짝 알고 있다
목표는 실제로 웹사이트를 구현할 수 있는 프론트엔드 개발 수준

이런 경우에는 처음부터 너무 어려운 개념을 한꺼번에 집어넣기보다,
필요한 만큼만 순서대로 배우는 방식이 훨씬 잘 맞다.

공부 목표

최종 목표는 아래처럼 잡는 게 가장 현실적이다.

디자인 시안이나 참고 사이트를 보고
Next.js로 반응형 웹사이트 프론트엔드를 구현할 수 있는 상태

좀 더 구체적으로 말하면,

여러 페이지를 만들 수 있고
공통 레이아웃을 구성할 수 있고
컴포넌트로 UI를 분리할 수 있고
더미 데이터나 간단한 API를 연결할 수 있고
로딩/에러 처리까지 기본적으로 할 수 있는 수준

여기까지 되면 “Next.js로 프론트엔드 웹사이트를 만든다”는 목표에는 충분히 도달한 것이다.

어떤 순서로 공부해야 할까

1. JavaScript를 React/Next.js에 필요한 만큼만 공부하기

지금 단계에서 중요한 건 JavaScript를 완벽하게 공부하는 게 아니다.
React와 Next.js 코드를 읽고, 수정하고, 직접 작성할 수 있을 정도로 익히는 게 목표다.

우선 꼭 익혀야 할 것들:

변수 (let, const)
함수
조건문
객체 / 배열
배열 메서드 (map, filter)
구조분해할당
spread 문법
import / export
비동기 처리 (async/await)
fetch

특히 아래 3개는 정말 중요하다.

map
객체 / 배열 다루기
async/await

이건 React, Next.js에 들어가면 계속 보게 되는 기본기다.

이 단계에서 해보면 좋은 연습

카드 리스트 만들기
탭 UI 만들기
아코디언 만들기
JSON 데이터로 목록 출력하기

2. React 핵심 개념 익히기

Next.js는 React 기반이라 React를 아예 모르고 들어가면 힘들다.
하지만 지금 내 목표상 React를 깊게 파는 것보다는 자주 쓰는 핵심 개념 위주로 익히면 된다.

우선 배워야 할 것:

JSX
컴포넌트
props
state
이벤트 처리
조건부 렌더링
리스트 렌더링
입력값 처리
useEffect 기초

이 단계에서 중요한 건
HTML을 그대로 길게 쓰는 방식에서, 컴포넌트 단위로 나누는 사고방식으로 바꾸는 것이다.

React 단계 실습 예시

좋아요 버튼
모달
FAQ 아코디언
검색 필터
상품 리스트 UI

3. Next.js 입문하기

React 핵심을 어느 정도 익힌 뒤에는 Next.js로 넘어간다.
최신 기준으로는 App Router 중심으로 배우는 게 좋다.

이 단계에서 익혀야 할 것들:

app/ 폴더 구조
page.js
layout.js
파일 기반 라우팅
공통 레이아웃
Link
컴포넌트 분리
Server Component / Client Component 개념
"use client"가 필요한 상황

여기서 초보 입장에서 가장 중요한 감각은 이거다.

클릭, 입력, 탭 전환처럼 사용자 인터랙션이 있으면 Client Component
데이터 읽어서 화면만 그리는 용도면 Server Component부터 생각하기

처음에는 이 정도 감각만 있어도 충분하다.

4. 데이터 다루기

Next.js 공부가 어느 정도 되면,
정적인 화면만 만드는 단계에서 벗어나 데이터를 붙여봐야 한다.

처음엔 아주 간단하게 시작하면 된다.

JSON 파일 import
더미 데이터 연결
fetch()로 데이터 가져오기
로딩 상태 처리
에러 상태 처리

이 단계에서는 아직 아래 내용까지 무리해서 들어갈 필요는 없다.

데이터베이스 연결
인증
복잡한 캐싱
서버 액션 심화
상태관리 라이브러리

지금 목표는 프론트엔드 웹사이트 구현이기 때문에,
처음부터 백엔드 개념까지 다 끌어안지 않아도 된다.

5. 실제 웹사이트를 만들어보는 단계

결국 공부는 프로젝트를 해봐야 내 것이 된다.
개념만 계속 보면 “아는 것 같은데 못 만드는 상태”가 오래간다.

그래서 작은 사이트라도 직접 만들어보는 게 가장 중요하다.

프로젝트 1. 브랜드/회사 소개 사이트

구성 예시:

홈
소개
서비스
문의

이 프로젝트에서 배우는 것:

페이지 구성
공통 헤더/푸터
반응형 레이아웃
섹션 컴포넌트 분리

프로젝트 2. 콘텐츠 리스트 사이트

구성 예시:

목록 페이지
상세 페이지
카테고리 필터

이 프로젝트에서 배우는 것:

동적 라우팅
데이터 렌더링
카드 컴포넌트 재사용

프로젝트 3. 실무형 UI 구현

구성 예시:

상품 목록 + 상세
예약 페이지
대시보드 일부
관리자 화면 일부

이 프로젝트에서 배우는 것:

화면 구조 설계
컴포넌트 설계
유지보수 가능한 폴더 구조
실제 서비스형 UI 구현 감각

내게 맞는 공부 방식

내 경우에는 HTML/CSS가 강점이기 때문에
그 강점을 버릴 필요가 전혀 없다. 오히려 큰 장점이다.

그래서 가장 잘 맞는 공부 방식은 이거다.

개념 30%, 구현 70%

즉,

문법만 오래 보지 말고
작은 화면이라도 직접 만들고
정적인 HTML을 React 컴포넌트로 바꾸고
그걸 Next.js 페이지로 조립하는 식으로 가는 게 가장 효율적이다

공부할 때 기억할 흐름

Next.js 공부는 아래 흐름으로 이해하면 훨씬 쉽다.

HTML로 화면 만든다
반복되는 UI를 컴포넌트로 분리한다
props로 데이터 연결한다
Next.js 페이지로 배치한다
fetch나 더미 데이터로 내용을 붙인다
실제 사이트처럼 다듬고 배포한다

이 흐름이 잡히면
Next.js가 갑자기 어려운 기술처럼 느껴지지 않고,
“익숙한 퍼블리싱에서 한 단계 확장된 방식”으로 보이기 시작한다.

지금 단계에서 너무 욕심내지 않아도 되는 것

처음부터 아래 내용까지 다 하려고 하면 오히려 지친다.

TypeScript 심화
Redux / Zustand
테스트 코드
인증 시스템
서버 액션 심화
SEO 심화
미들웨어
복잡한 캐싱 전략

이건 나중 단계에서 필요할 때 추가하면 된다.
지금은 프론트엔드 웹사이트 구현 능력을 먼저 만드는 게 더 중요하다.

8주 정도로 보면 이런 흐름

1~2주차

JavaScript 기초
배열 / 객체
map, filter
async/await
fetch

3주차

React 기초
컴포넌트
props / state
이벤트 처리
조건부 렌더링
리스트 렌더링

4주차

React 미니 프로젝트
모달 / 탭 / 필터 UI

5주차

Next.js 시작
App Router 구조
page.js, layout.js
Link
컴포넌트 분리

6주차

정적 사이트 제작
공통 레이아웃
반응형 페이지 구성

7주차

데이터 연결
상세 페이지
로딩 / 에러 처리

8주차

실전 프로젝트 완성
배포
리팩토링

내가 앞으로 공부할 때 체크할 기준

잘 가고 있다는 신호

HTML을 보면 어떤 컴포넌트로 나눌지 떠오른다
반복 UI를 props로 바꿀 수 있다
폴더 구조로 페이지를 만들 수 있다
더미 데이터로 먼저 화면을 만들 수 있다
콘솔 에러가 나와도 덜 겁난다

아직 더 익숙해져야 하는 신호

map()이 아직 낯설다
state가 왜 필요한지 흐릿하다
Client / Server Component 구분이 어렵다
폴더 구조를 매번 감으로 만든다

결론

지금 내 상황에서 Next.js 공부는
“처음부터 완벽하게 이해하는 공부”보다
실제로 만들 수 있게 되는 공부가 더 중요하다.

내 강점은 HTML/CSS이고,
부족한 부분은 JavaScript와 React 기본기다.

그래서 가장 좋은 순서는 아래와 같다.

JavaScript 기초 → React 핵심 → Next.js App Router → 작은 프로젝트 → 실제 웹사이트 구현

결국 가장 중요한 건 이 한 문장으로 정리된다.

정적인 HTML을 React 컴포넌트로 바꾸고, 그걸 Next.js 페이지로 조립하는 힘을 기르는 것

이 방향으로 가면
초보자여도 충분히 Next.js로 웹사이트 프론트엔드를 만들 수 있는 수준까지 갈 수 있다.

[Figma] 이미지 Export 설정 항목 설명

아랄라랄라 — Tue, 29 Jul 2025 09:01:31 +0900

피그마 Export 창

왼쪽 설정창 (세부 Export 옵션)

Ignore overlapping layers

겹치는 레이어 무시

체크 시: 겹쳐진 레이어 중 가려진 부분은 렌더링에서 제외됨
용도: 불필요한 픽셀 연산을 줄이고 최적화된 출력 이미지 생성

Include bounding box

바운딩 박스 포함

체크 시: 레이어의 바운딩 박스를 기준으로 Export
예: 실제 요소보다 드롭 섀도우 등으로 영역이 넓어진 경우, 그 영역까지 포함

Color profile: sRGB (standard)

이미지에 색상 프로파일 포함 여부
sRGB는 웹표준 색상 공간으로, 일반적인 PNG나 JPG에 적합
인쇄용은 CMYK, 웹/모바일은 sRGB 권장

Image resampling: Detailed

이미지 크기 변경 시 품질 보정 방식
Detailed: 고해상도에서 더 나은 결과를 얻기 위한 고품질 보간 방식 사용
옵션에 따라 Simple, Detailed, Smooth 등이 있음

Suffix: None

Export 되는 파일명에 붙는 접미사
예: @2x, _web, _dark 등을 설정 가능

오른쪽 Export 패널

2x / PNG / Export 메인

2x: 2배 크기로 출력 (고해상도 디스플레이 대응)
PNG: 투명 배경이 가능한 이미지 형식
Export 메인: 현재 선택된 프레임(이름이 '메인')을 Export하겠다는 의미

필요에 따라 설정값을 바꾸면 다음과 같은 목적에 맞게 Export 가능

웹/앱 썸네일	PNG, 1x 또는 2x, sRGB, Include bounding box O
투명 배경 아이콘	PNG, Ignore overlapping O, Include bounding box X
최고 화질 포스터	PNG or JPG, 2x 이상, Image resampling = Detailed