Next.js

 

Next.js 정의

• SSR(서버 사이드 렌더링)과 그 파생 기술들을 다루는 프레임워크
• "React라는 '화면 도구'에 Node.js라는 '서버 엔진'을 장착한, 풀스택 웹 프레임워크입니다."

 

1. Next.js의 역할

Next.js는 한 지붕 아래 두 가지 자아를 가지고 있습니다.

• 프론트엔드 자아 (React): 컴포넌트를 만들고, 사용자의 클릭에 반응하고, 예쁜 화면을 그립니다.
• 백엔드 자아 (Node.js 서버): 브라우저가 아니라 서버에서 코드를 실행합니다. 데이터베이스에 직접 접속하거나, API를 생성하고, 환경변수를 안전하게 관리합니다.

 

2. React와 NextJs 비교

• React (SPA): 단일 HTML(index.html) 위에서 자바스크립트가 컴포넌트 단위로 UI를 동적으로 교체하는 방식입니다. 본질적으로는 **'웹 사이트'라기보다 브라우저에서 돌아가는 '웹 애플리케이션'**을 만드는 데 최적화되어 있습니다.
• Next.js: React의 SPA적 장점을 유지하면서, 이를 **파일 시스템 기반 라우팅(Directory 기반)**과 결합하여 서버 사이드 렌더링(SSR)이 가능하게 만든 프레임워크입니다. 즉, 여러 개의 SPA 페이지를 서버가 효율적으로 관리하고 배포하는 풀스택 구조라고 볼 수 있습니다.

 

3. Next.js의 장점.

• 검색 엔진 최적화 (SEO)
• 성능과 초기 로딩 속도 (FCP)
• 보안과 데이터 처리의 효율성
  •  서버 컴포넌트나 API Routes를 통해 서버 내부에서 은밀하게 데이터를 가져온 뒤, 결과값만 안전하게 브라우저에 전달합니다. 환경변수 분리가 바로 이 목적을 위한 핵심 장치입니다.
•  이 과정에서 발생하는 이슈: "서버에서 미리 그리는 코드"와 "브라우저에서 실행될 코드"가 섞여 있기 때문에, 환경변수 설정 시 이 변수가 어디서 쓰일지(NEXT_PUBLIC_ 여부)를 결정해야 하는 복잡함이 생깁니다.

 

4. Next.js 학습 유의사항

  Next.js를 공부할 때는 **브라우저 밖(서버)**의 영역을 함께 고민해야 합니다. 사용자님이 혼란스러워하셨던 '백엔드 맥락'이 바로 여기서 나옵니다.

• 렌더링 전략 (SSR/SSG/ISR): 이 화면을 서버에서 그려서 보낼 것인가, 아니면 브라우저에서 그리게 할 것인가?
• 라우팅 (File-based Routing): 폴더 구조가 어떻게 주소(URL)가 되는가?
• 서버 컴포넌트 vs 클라이언트 컴포넌트: 어떤 코드는 서버에서만 돌고, 어떤 코드는 브라우저까지 전달되는가? (여기서 환경변수 문제가 발생하죠!)
• 데이터 페칭: useEffect로 데이터를 가져오는 게 아니라, 서버 환경에서 직접 DB나 API를 호출하는 법.
• 학습 목표: "성능, 보안, 검색 엔진 최적화(SEO)를 고려해 서비스의 전체 흐름을 제어하는 것."

표준디렉토리구조

src/
├── @core/                    # 핵심 재사용 가능한 컴포넌트들 (템플릿/라이브러리)
│   └── components/           # 여러 페이지에서 재사용되는 UI 컴포넌트
│       └── charts/
│           └── template/
│               └── VehicleTemplate.tsx  # 차량 통계 페이지의 UI 템플릿
│
├── model/                    # TypeScript 타입 정의 (데이터 구조)
│   └── statistics/
│       └── StatisticsModel.ts  # 통계 관련 인터페이스 정의
│
├── enum/                     # 상수/열거형 정의
├── service/                  # API 호출 로직
├── utils/                    # 유틸리티 함수
└── pages/                    # 실제 페이지들

• src: 전체 프론트엔드 소스 코드
• @core: 재사용 가능한 핵심 컴포넌트들 (여러 페이지에서 공통으로 사용). 특정 페이지의 비즈니스 로직에 종속되지 않는, 순수 UI나 공통 기능을 포함합니다.
• components: UI 컴포넌트를 말합니다 (버튼, 차트, 테이블 등)
• model/ & enum/ (데이터 설계도) : TypeScript의 Interface나 Type을 정의합니다. API에서 오는 데이터가 어떻게 생겼는지 정의하므로, 프론트엔드 전체에서 가이드라인 역할을 합니다.
• enum/: 상태 코드(예: WAITING, SUCCESS)나 상숫값들을 관리합니다. 코드에 직접 문자열을 입력하는 "Magic String"을 방지하여 에러를 줄여줍니다.
• service/: Axios나 Fetch를 사용하여 서버와 통신하는 함수들이 모여있습니다. 데이터 가공 전 단계의 입출력을 담당합니다.
• pages/ (최종 결합부) : 실제 브라우저 주소(URL)와 매칭되는 컴포넌트들입니다. 여기서 service를 호출해 데이터를 가져오고, 그 데이터를 @core에 있는 VehicleTemplate에 주입하여 화면을 완성합니다.

 데이터 흐름

  1. service/ (API 호출)
     ↓
  2. model/ (DTO - 데이터 타입)
     ↓
  3. component/ (UI 렌더링 - 재사용 가능)
     ↓
  4. pages/ (실제 페이지 - 라우팅)

  Page vs Component 차이

  Component (@core/components/charts/template/VehicleTemplate.tsx)

  // 재사용 가능한 UI 템플릿 (데이터만 주면 어디서든 사용 가능)
  export const VehicleTemplate = ({ data, onDownload }) => {
    return (
      <Box>
        <Typography>{data.totalCount}</Typography>
        <Table data={data.dataList} />
        <Chart data={data.chartData} />
      </Box>
    )
  }
  - 역할: 순수 UI 렌더링 (받은 데이터를 화면에 그림)
  - 특징: 여러 페이지에서 재사용 가능
  - URL 없음: 직접 접근 불가

  Page (pages/statistics/vehicle.tsx)

  // 실제 페이지 - 데이터 로딩 + 컴포넌트 조합
  import { VehicleTemplate } from '@core/components/...'
  import { useVehicleStats } from 'src/service/...'

  export default function VehicleStatsPage() {
    // 1. API에서 데이터 가져오기
    const { data } = useVehicleStats()

    // 2. 이벤트 핸들러 정의
    const handleDownload = () => { ... }

    // 3. 컴포넌트에 데이터 주입
    return (
      <Layout>
        <VehicleTemplate 
          data={data} 
          onDownload={handleDownload} 
        />
      </Layout>
    )
  }
  - 역할: 데이터 로딩 + 비즈니스 로직 + 컴포넌트 조합
  - 특징: Next.js 파일 기반 라우팅
  - URL 있음: /statistics/vehicle → 이 파일 실행

 

환경변수관리

1. React (CRA/Vite 기반) 환경변수 관리

React는 빌드 후 정적 파일만 남습니다. 즉, 모든 환경변수는 빌드 타임에 결정됩니다.

• 변수명 규칙: * CRA: REACT_APP_으로 시작 (예: REACT_APP_API_URL)
  • Vite: VITE_으로 시작 (예: VITE_API_URL)
• 작동 원리: 빌드 시점에 코드를 훑으며 해당 변수를 실제 값으로 글자 치환(Text Replacement) 합니다.
• 변경: 빌드된 파일을 서버(Nginx 등)에 올린 후에는 환경변수를 바꿀 수 없습니다. (다시 빌드해야 함)

 

2. Next.js 환경변수 관리

 

Next.js는 서버(Node.js)가 있기 때문에 변수를 공개용과 비공개용으로 엄격히 분리합니다.

① 브라우저용 (Public)

• 규칙: NEXT_PUBLIC_ 접두사를 붙임 (예: NEXT_PUBLIC_ANALYTICS_ID)
• 특징: React와 동일하게 빌드 시 JS 번들에 포함됩니다. 브라우저에서도 접근 가능(console.log로 보임)합니다.

② 서버 전용 (Private)

• 규칙: 접두사 없음 (예: DB_PASSWORD, API_SECRET_KEY)
• 특징: 오직 Node.js 서버 환경(getServerSideProps, API Routes)에서만 읽을 수 있습니다.
• 보안: 브라우저 JS 파일에는 절대 포함되지 않으므로 매우 안전합니다.
• 변경: 서버가 실행될 때마다 값을 읽으므로, 빌드 후에도 서버 환경변수를 수정하고 재시작하면 즉시 반영됩니다.