Next.js + Typescript 적응기 #1: 프로젝트 구조와 개념 정리

새로운 프로젝트에 참여하게 되었습니다.

내가 좋아했던 조합은 JS + Vite를 활용한 조합이었는데, ts + Next.js 조합을 사용하게 되어 Ts는 공부를 해놨지만, Next는 약간 미숙하여 정리하는 카테고리를 신설했습니다.

 

Next.js를 처음 접하면 폴더 구조와 파일의 역할이 헷갈립니다.

 

특히, index.ts, page.tsx, .ts와 .tsx의 차이 등을 명확히 이해하는 것이 중요합니다.

사실 별건 아닐지라도, 처음 접하거나 미숙한 사용자에게 도움이 되었으면 합니다.

 

이번 포스팅에서는 Next.js의 프로젝트 구조와 핵심 개념을 정리해보겠습니다.

---

Next.js의 파일 구조와 역할

깃허브에 다른 사람 레포를 보면 아니 왜 폴더마다 index.ts가 있지. 싶을겁니다

1.  index.ts의 역할 (Entry Point)

• index.ts는 폴더의 엔트리 포인트(Entry Point) 역할을 합니다.
• 폴더 내 여러 파일을 한 번에 내보낼(export) 수 있도록 정리하는 기능을 합니다.
• index.ts가 있으면 폴더명을 import할 때 더 간결하게 사용할 수 있습니다.

예제 (폴더 구조)

📂 utils
 ├── index.ts   # 폴더의 기본 export 관리
 ├── localStorage.ts
 ├── dateFormatter.ts

index.ts 코드 예제

// 📂 utils/index.ts
export * from "./localStorage";
export * from "./dateFormatter";

index.ts가 있으면 다른 파일에서 다음과 같이 import할 수 있음.

import { getIsFirstTimeUser } from "@/utils"; // ✅ 가능
// import { getIsFirstTimeUser } from "@/utils/localStorage"; // ❌ 굳이 이렇게 안 써도 됨

 

참고로 import path 앞의 #은 절대경로로써, ../../ 이렇게 했던 기존의 방식보다 업그레이드 된 방식입니다.

 

설정하는법은 tsconfig.json에서 아래와 같이 설정하면 됩니다.

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

✔ 이점: index.ts 덕분에 파일별로 직접 경로를 지정하지 않고 폴더 단위로 가져올 수 있음.

---

2. page.tsx는 라우팅(Route) 포인트

Next.js에서는 app 디렉터리 내에서 page.tsx 파일이 있으면 해당 폴더가 URL 경로(Route) 가 됩니다.

 예제 (폴더 구조)

📂 app
 ├── 📂 home
 │   ├── page.tsx   # /home 경로로 매핑
 ├── 📂 login
 │   ├── page.tsx   # /login 경로로 매핑

자동으로 URL 경로가 생성됨

• app/home/page.tsx → example.com/home
• app/login/page.tsx → example.com/login

✔ 이점: Next.js의 파일 기반 라우팅(File-Based Routing) 덕분에, 별도의 설정 없이도 폴더 구조만으로 라우트를 쉽게 만들 수 있음.

vite에서는 최상위 컴포넌트인 app.jsx에서 따로 라우팅을 해주었는데, 장단점이 있겠지만 Next에는 폴더 구조만으로 비유하자면 자동라우팅이 가능하다 라고 볼 수 있겠습니다.

---

3. .tsx vs .ts 의 확장자 선택의 기준

확장자 사용 목적은 표로 정리했습니다.

.tsx	React 컴포넌트	JSX(HTML-like syntax)를 포함함
.ts	비(非)컴포넌트 파일	순수 TypeScript 코드 (함수, API 호출, 타입 정의 등)

예제: .tsx (컴포넌트 UI 포함)

const OnboardingModal = () => {
  return (
    <div className="modal">
      <h1>Welcome!</h1>
    </div>
  );
};
export default OnboardingModal;

✔ JSX가 포함되므로 .tsx 사용

✅ 예제: .ts (비(非) UI 코드)

export const getIsFirstTimeUser = (): boolean => {
  const value = localStorage.getItem("isFirstTimeUser");
  return value === "true";
};

✔ JSX 없이 순수한 로직만 포함되므로 .ts 사용

---

마지막 간결한 정리

1. index.ts → 폴더의 대표적인 내보내기 관리 (import를 간결하게)
2. page.tsx → Next.js에서 해당 폴더를 라우팅(Route) 포인트로 사용
3. .tsx → React 컴포넌트(UI 포함) 파일에 사용
4. .ts → 기능(함수, API 호출, 타입 정의 등) 관련 파일에 사용