[React] Next.js로 React와 TypeScript 환경 설정하기

📌 Next.js + React + TypeScript

• Next.js : React 기반 프레임워크
• React : UI를 구성하는 라이브러리
• TypeScript : 정적 타입을 추가하여 JavaScript의 기능을 향상시키는 언어

Next.js가 모든 개발, 빌드, 배포 과정을 통합적으로 관리합니다.

즉, Next.js가 설치된 환경에서는 모든 작업을 수행할 수 있습니다.

---

📌 Vite + React + TypeScript (기존 사용 방식)

• Vite : 빠른 개발 서버와 빌드를 지원하는 도구
• React : UI를 구성하는 라이브러리
• TypeScript : 정적 타입 추가

Vite가 개발 서버와 빌드를 처리하지만, 실제 배포는 별도로 진행해야 합니다.

따라서 Vite를 사용할 경우, 배포 과정은 추가적인 설정이 필요합니다.

 

---

🗂️ Next.js + React + TypeScript 프로젝트 생성

⭕ 터미널 열기 : Ctrl + Shift + `
❌ 터미널 프로세스 종료 : Ctrl + C

---

✅ 프로젝트 초기화

새로운 Node.js 프로젝트를 생성하고 기본적인 '📜package.json' 파일을 만듭니다.

-y 옵션은 기본 설정으로 바로 생성합니다.

npm init -y

 

---

✅ Next.js 프레임워크, React 및 ReactDOM 라이브러리 설치

• next : React 기반의 Next.js 프레임워크
  (서버 사이드 렌더링, 정적 사이트 생성, API 라우팅 지원)
• react : UI를 구축하기 위한 라이브러리(Next.js가 React 기반)
• react-dom
  React 컴포넌트를 DOM에 렌더링하여 Next.js 페이지를 브라우저에 표시
  매핑된 페이지가 사용자에게 보여지기 위해 필요

npm i next react react-dom

 

---

⚙️ package.json 설정 수정 (ES 모듈 사용)

"type": "module" ➡️ ES 모듈 방식 사용

// ▶ ⚙️package.json
{
  "name": "study",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "next": "^14.2.15",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}

 

---

⚙️ next.config.js 설정 새 파일 생성

Next.js 애플리케이션을 실행하기 위한 설정 파일입니다.

다양한 설정을 통해 프로젝트의 동작 방식을 조정할 수 있습니다.

 

basePath: "/app" 설정 시 ➡️ http://localhost:3000/app 접속

// ▶ ⚙️next.config.js
export default {
    reactStrictMode: true,
    env: {
        API_PATH: "https://www.naver.com"
    },
    pageExtensions: ["js","jsx","ts","tsx"],
    trailingSlash: false,
    poweredByHeader: false,
    outputFileTracing: true
}

설정 옵션	설명
reactStrictMode: boolean	리액트의 엄격 모드 활성화 성능이 큰 이유로 개발 서버 실행 중에만 사용되며, 렌더링 시 두 번 실행되어 잠재적인 문제를 조기에 발견
env: { "키값": any }	환경 변수 만드는 속성 생성한 환경 변수는 process.env.키값 통해 접근 클라이언트 측에서도 사용 가능
basePath: string	웹사이트의 기본 경로를 설정 아래 형식으로 URL 구성 기본 : 도메인/서브/경로 설정 시 : 도메인/기본경로/서브/경로
assetPrefix: string	외부 사이트에서 자산(파일)을 가져올 때 사용 src 또는 href 속성으로 파일을 연결할 때, public 폴더에 있는 파일이 아닌  외부 사이트에서 불러옵니다. assetPrefix: "https://www.naver.com" 설정 시 src="/file"로 지정할 때 자동으로 https://www.naver.com/file 변경
pageExtensions: [...string]	Next.js 사용될 파일 확장자 정의 pageExtensions: ["js", "jsx", "ts", "tsx"]
i18n: { locales: [...string], defaultLocale: string, localeDetection: boolean }	다국어 지원을 위한 설정 locales ➡️ 지원할 언어의 배열 defaultLocale ➡️ 기본 언어 설정 localeDetection ➡️ 자동으로 브라우저 언어를 감지하여 언어를 변경할지 여부 ※ CommonJS 모듈에서만 사용 가능
trailingSlash: boolean	URL 경로의 마지막에 /를 붙일지 여부
poweredByHeader: boolean	Next.js가 자동으로 헤더에 X-Powered-By: Next.js를 추가 보안상의 이유로 이 헤더를 제거하려면 false로 설정
images: { domains: [...string], deviceSizes: [...number] }	이미지 최적화를 위한 설정 import Image from 'next/image'; 가져온 후 <Image /> 태그를 사용하여 특정 디바이스 크기에 맞춰 이미지를 자동 압축
redirects: function => [...{ source: string, destination: string, permanent: boolean }]	특정 경로(source)로 접근할 때, 지정된 경로(destination)로 자동 리다이렉트
rewrites: function => [...{ source: string, destination: string }]	특정 경로(source)로 접근할 때, 해당 요청을 지정된 경로(destination)로 전달(포워딩)합니다. 사용자는 원래의 URL을 보지만, 실제로는 다른 경로에서 콘텐츠 로드
headers: function => [...{ source: string, headers:[...{key: string, value: string}] }]	특정 경로(source)에 대해 사용자 정의 헤더를 추가 이 헤더는 클라이언트 요청에 포함되어 서버로 전달
outputFileTracing: boolean	빌드 시 사용된 파일만 포함할지 여부 보통 true 설정

 

---

🗂️ Next.js 주요 폴더 구조 (4가지)

.study/project
├── 🗂️ components
├── 🗂️ pages
├── 🗂️ public
└── 🗂️ styles

폴더명	설명
🗂️ components	리액트 컴포넌트를 저장하는 폴더 UI의 기본이 되는 컴포넌트를 포함 폴더명 변경 가능
🗂️ pages	Next.js 고정 폴더명 화면에 표시될 페이지를 저장하며, 이 안의 파일은 각각 URL 경로로 매핑 SSG(정적 사이트 생성)에서는 경로별로 HTML 파일이 자동 생성
🗂️ public	Next.js 고정 폴더명 정적 파일(이미지, 폰트 등) 저장 이 폴더의 파일은 base URL(/) 경로 접근 📁 fonts : 폰트 관리(ttf 형식 권장) 📁 icons : svg 파일 관리 📁 images : jpg, png 등 이미지 파일 관리
🗂️ styles	Next.js 고정 폴더명 CSS 스타일 파일 저장 Tailwind CSS와 같은 기본 CSS 프레임워크를 사용

 

---

🗂️ components 폴더 구조

리액트 컴포넌트를 저장하는 폴더로, UI의 기본이 되는 컴포넌트 포함

파일명	설명
🗂️components	Next.js 프로젝트에서 모든 UI 컴포넌트를 저장하는 폴더
🗂️components/📁common	여러 페이지에서 공통으로 사용하는 컴포넌트 📜(버튼) Button.tsx 📜(입력필드) Input.tsx 📜(로딩스피너) Loader.tsx 📜(모달) Modal.tsx
🗂️components/📁layout	레이아웃 컴포넌트 📜(헤더) Header.tsx 📜(푸터) Footer.tsx 📜(사이드바) Sidebar.tsx
🗂️components/📁sections	페이지 내에서 특정 섹션에 대한 컴포넌트 📜(추천사 섹션) Testimonials.tsx 📜(연락처 폼) ContactForm.tsx
🗂️components/📁pages	페이지 별로 나뉜 컴포넌트 📜(홈 페이지) HomePage.tsx 📜(소개 페이지) AboutPage.tsx 📜(연락처 페이지) ContactPage.tsx
🗂️components/📁UI	UI 관련 컴포넌트 📜(카드) Card.tsx 📜(툴팁) Tooltip.tsx 📜(드롭다운) Dropdown.tsx

 

---

🗂️ pages 폴더 구조

Next.js에서는 React와 다르게 라우트를 따로 설정할 필요가 없습니다.

pages 디렉토리에 있는 .js, .jsx, .ts, .tsx 파일이 자동으로 라우트를 설정해줍니다.

즉, 복잡한 설정 없이 pages 디렉토리의 파일 이름이 그대로 URL 경로가 됩니다.

파일명	설명
🗂️pages	Next.js 프로젝트에서 웹사이트에 표시될 모든 페이지를 저장하는 폴더 🗂️pages/🌐index.tsx → http://localhost:3000/ 🗂️pages/🌐sub.tsx → http://localhost:3000/sub
🗂️pages/📁api	웹사이트와 데이터를 주고받는 파일들이 들어있는 폴더 사용자 요청에 응답하는 기능 수행
🗂️pages/🌐_app.tsx	모든 페이지에서 공통으로 사용되는 컴포넌트를 정의하는 파일 주로 페이지의 레이아웃이나 스타일을 설정
🗂️pages/🌐index.tsx	기본 페이지 파일, 웹사이트의 첫 번째 페이지(/) 사용자가 사이트에 들어왔을 때 처음 보는 페이지 http://localhost:3000/

---

🔎 파일 생성 방법

pages 폴더에 파일을 만들고, 그 파일에 하나의 함수만 정의한 후 export default를 하면 됩니다.
그러면 파일명이 경로로 사용됩니다.

 

사용예시

// ▶ 🗂️pages/🌐index.tsx
import React from 'react';

export default function Home() {
   return <div>
       Hello
   </div>
}

 

---

🔎 SSR과 SSG (서버 측 렌더링과 정적 사이트 생성)

Next.js에서는 pages 폴더 내에서만 SSR과 SSG를 사용할 수 있습니다.

Next.js에서 SSR(getServerSideProps) / SSG(getStaticProps) 함수를 사용하지 않으면

Next.js는 기본적으로 페이지를 미리 만들어 놓습니다. (프리렌더링)

사용자가 페이지를 요청하면, 해당 페이지의 HTML이 서버에서 생성되어 사용자에게 전송됩니다.

이 방식은 실제 SSR은 아니지만, 사용자에게는 SSR처럼 느껴질 수 있습니다.

 

➡️ SSR (getServerSideProps)

사용자가 페이지를 요청하면 서버가 HTML을 생성하여 클라이언트에 전달하는 방식입니다.

이때, 매 요청마다 최신 데이터를 가져오기 위해

getServerSideProps 함수를 사용하고, 이 데이터는 페이지 컴포넌트에 전달됩니다.

이 과정은 서버에서만 실행되며 브라우저에서는 실행되지 않습니다.

SSR은 동적으로 데이터를 가져오는 데 유용하지만,

getStaticProps보다 성능이 떨어지고 CDN에 캐싱되지 않아 느릴 수 있습니다.

따라서 Next.js는 꼭 필요한 경우에만 getServerSideProps를 사용하라고 권장합니다.

// 1️⃣ SSR 데이터 가져오는 함수 export
export async function getServerSideProps() {
    // ▶ 외부 API로 데이터 가져오기
    const res = await fetch(`https://api.example.com/data`);
    const data = await res.json();

    // ▶ 페이지 컴포넌트의 props에 데이터 전달
    return { props: { post: data } }; 
}


// 2️⃣ SSR 렌더링 데이터 받아오기
export default function Home({ post }) {
   return <div>
       <h1>SSR로 받은 데이터</h1>
       {post ? (
           <>
               <div>날짜: {post.date}</div>
               <div>제목: {post.title}</div>
               <div>설명: {post.desc}</div>
           </>
       ) : (
           <div>데이터를 불러오는 중입니다.</div>
       )}
   </div>
}

 

➡️ SSG (getStaticProps)

빌드 시 한 번만 호출되며, static file로 HTML이 미리 생성됩니다. 
getStaticProps 함수를 사용하여 데이터를 가져오고, 이 데이터는 페이지 컴포넌트에 전달됩니다. 
빠르고 효율적이며, 사용자는 SSG로 생성된 페이지를 직접 볼 수 있습니다. 
revalidate 값을 추가하면, 설정한 시간 후에 페이지를 다시 생성하여 최신 데이터를 반영할 수 있습니다.

// 1️⃣ SSG 데이터를 가져오는 함수 export
export async function getStaticProps() {
    // ▶ 외부 API로 데이터 가져오기
    const res = await fetch(`https://api.example.com/data`);
    const data = await res.json();
    
    // ▶ 페이지 컴포넌트의 props에 데이터 전달
    return { 
         props: { data },
         revalidate: 10   // 10초마다 페이지 갱신
    };
}


// 2️⃣ SSG 렌더링 데이터 받아오기
export default function Home({ data }) {
   return <div>
       <h1>SSG로 받은 데이터</h1>
       {/* ▶ JSON 형태로 데이터 표시 */}
       <div>{data ? JSON.stringify(data) : "데이터를 불러오는 중입니다."}</div>
   </div>
}

 

---

🗂️ public 폴더 구조

이미지, 폰트 등의 정적 자산을 관리하는 폴더

Next.js에서는 /public 디렉토리 내의 파일에 직접 접근할 수 있습니다.

파일명	설명
🗂️public	Next.js 프로젝트에서 정적 파일(이미지 등)을 저장하는 폴더
🗂️public/📁fonts	웹사이트에 사용되는 폰트 관리 (TTF, OTF, WOFF, WOFF2 형식 권장)
🗂️public/📁icons	웹사이트에 사용되는 아이콘 관리 (SVG 파일 포함)
🗂️public/📁images	JPG, PNG 등의 이미지 파일 관리
🗂️public/📁videos	웹사이트에 사용되는 비디오 파일 관리
🗂️public/📁documents	PDF, DOCX 등 문서 파일 관리
🗂️public/📁audio	오디오 파일 관리
🗂️public/📁uploads	사용자 업로드 파일 관리

 

---

🗂️ styles 폴더 구조

웹사이트의 스타일 파일(CSS)을 저장 폴더

styles 폴더 안의 CSS 파일을 사용하려면 필요한 컴포넌트나 페이지에서 import해야 합니다.

 

🔎 전역 스타일과 모듈 스타일

• globals.css : 모든 페이지와 컴포넌트에 전역으로 적용되는 스타일을 정의 파일
• module.css : 특정 컴포넌트나 페이지에서만 사용되는 스타일을 정의 파일

파일명	설명
🗂️styles	스타일 파일(css) 저장하는 폴더
🗂️styles/🎨globals.css	모든 페이지와 컴포넌트에 전역으로 적용되는 스타일 파일
🗂️styles/🎨index.module.css	pages 폴더 안에 index.tsx에만 적용되는 스타일 파일
🗂️styles/🎨사용컴포넌트명.module.css	components 폴더 안의 특정 컴포넌트에만 적용되는 스타일 파일 Header.module.css 특정 컴포넌트명 사용

 

---

⚙️ package.json 설정 수정 (단축어 설정)

'📜package.json' ➡️ scripts 카테고리에 단축어 추가

// ▶ ⚙️package.json
"scripts": {
    "dev": "npx next dev",
    "build": "npx next build",
    "start": "npx next start",
},

 

[개발서버 실행]  npx next dev

• 단축어 :  npm run dev 
• Next.js 개발 빌드 시작
• 수정한 코드가 서버에 즉시 적용

[빌드]  npx next build

• 단축어 :  npm run build 
• 개발이 끝난 후, 애플리케이션을 빌드
• getServerSideProps를 사용하면 매 요청마다 SSR을 하고, 
  getStaticProps를 사용하면 SSG로 빌드 시에만 HTML을 생성합니다. 
  SSR이나 SSG 함수를 사용하지 않은 페이지는 
  Next.js가 기본적으로 프리렌더링을 사용하여 요청한 페이지의 
  초기 HTML 파일을 서버에서 생성해 클라이언트로 전송합니다.

[배포]  npx next start

• 단축어 :  npm start 
• 빌드된 CSR, SSR, SSG 파일로 실제 서비스 제공

 

---

🎯 Next.js 로컬 개발 서버 실행

Next.js 개발 서버를 실행하여 로컬에서 애플리케이션을 미리 볼 수 있습니다.
웹 브라우저에서 http://localhost:<포트> 주소로 접근할 수 있으며,

이 서버는 실시간으로 코드를 테스트하고 수정하는 데 사용됩니다.

npm run dev

 

---

🌐 브라우저 실행

http://localhost:3000

 

---