해커톤에서 사용할 수 있는 다양한 프론트엔드(react, next) 빌드 및 배포 방법

지금까지 해커톤 및 사이드 프로젝트를 진행하면서 여러 방법으로 React와 Next를 빌드하고 배포하다 보니 한 번쯤은 정리해보고 싶어서 이번 포스팅에서는 저만의 프론트엔드 빌드 및 배포 노하우를 공유드리고자 합니다.

 

1. React 빌드 및 배포

먼저 옛날에 가장 많이 사랑받았던 React 빌드 및 배포 방법에 대해 설명드리겠습니다. 불과 3~4년 전만 해도 React 공식가이드 문서에서 튜토리얼로 활용되었으며 아마 여러분들에게 가장 친숙할 거라 생각되는 create-react-app이라는 명칭의 React 부트스트랩(이하 CRA) 그리고 CRA에 내장된 기본 템플릿을 활용해서 빌드하는 방법입니다.

 

🐣 프로젝트 init

npm install -g create-react-app
create-react-app [프로젝트명]

 

React 15~17 버전에서 많이 사용된 방법입니다. 반드시 Node.js 패키지(node_modules)에 CRA 도구를 설치해야 사용할 수 있었기 때문에 최초 설치시 글로벌 변수(-g)를 붙여야 했고 로컬에 계속 무겁게 들고 있어야 한다는 단점이 있었습니다.

 

하지만 이후에는 npm 대신 npx (설치 후 실행) 라는 명령어가 추가되면서 로컬에 CRA가 없더라도 템플릿을 받아서 사용할 수 있게 되었습니다.

 

create-react-app [프로젝트명] 명령어로 기본 템플릿을 통해 보일러 플레이트를 구성하고 나면 package.json에 빌드 명령문이 자동으로 세팅이 되어 나오므로 명령어만 입력하면 바로 간단하고 빠르게 빌드를 실행할 수 있습니다.

 

🛠️ 빌드

npm run build

빌드를 실행하면 프로젝트 루트 경로에 build 폴더가 생기는데 그 안에 static 한 구조의 index.html파일과 압축된 css, js 파일들이 있는 것을 보실 수 있습니다. 이 build폴더를 웹 서버가 바라볼 수 있게 설정하고 띄우시기만 하면 됩니다.

 

🚀 배포

# nginx 설정파일
server {
    server_name 도메인 주소 입력;
    location / {
      root 프로젝트 경로 입력/build;
      index index.html;
      try_files $uri $uri/ =404;
    }
}

 

배포는 Nginx 웹 서버 설정을 기준으로 설명드리도록 하겠습니다. 다음과 같이 build폴더를 서버로 올린 뒤에 Nginx 설정 파일에 build 폴더를 연결한 뒤 서버를 재기동하시면 됩니다.

 

---

 

2. React PWA 빌드 및 배포

PWA는 Progressive Web App의 약자로서 웹을 앱 처럼 동작하도록 빌드하는 기능입니다. 실제 앱처럼 푸시 알림, 자이로센서 등도 사용 가능하고 디바이스에 설치도 가능합니다. PWA도 마찬가지로 CRA를 통해 cra-template-pwa라는 템플릿으로 프로젝트를 생성해서 보일러 플레이트를 구성하시면 됩니다.

 

🐣 프로젝트 init

npx create-react-app [프로젝트명] --template cra-template-pwa

 

기존에 이미 CRA 기본 템플릿으로 구성해놓은 프로젝트가 있다면 PWA 템플릿에서 제공하고 있는 아래 파일들을 따로 빼서 옮겨도 됩니다.

 

• service-worker.js : 서비스 워커 (캐싱, 백그라운드 동기화, 푸시 알림 등 작업 이벤트 등록)
• serviceWorkerRegistration.js : 서비스 워커 등록 및 상태 관리
• manifest.json : 앱의 아이콘, 배경, 시작 경로 등을 지정

 

🛠️ 빌드

npm run build

 

빌드는 CRA 기본 템플릿을 빌드할 때와 마찬가지로 위 명령어를 실행하는 경우 프로젝트 루트 경로에 build 폴더가 생기고 해당 파일을 웹 서버에 올려서 사용하시면 됩니다.

 

❗빌드시 주의할 점) 서비스워커 등록

스마트폰에서 앱으로 실행되는 서비스이기 때문에 빌드 전에 백그라운드 환경에서도 서비스가 작동할 수 있도록 서비스 워커를 등록해야 합니다.
index.js에 serviceWorkerRegistration.unregister()를 serviceWorkerRegistration.register()로 변경

 

🚀 배포

server {
    server_name 도메인 주소 입력;
    location / {
      root 프로젝트 경로 입력/build;
      index index.html;
      try_files $uri $uri/ =404;
    }
}

 

CRA 기본템플릿 빌드할 때와 마찬가지로 다음과 같이 build폴더를 서버로 올린 뒤에 웹 서버(nginx) 설정 파일에 build 폴더를 연결한 뒤 서버를 재기동하시면 됩니다.

 

---

 

3. Next 빌드 및 배포

다음은 Next 프레임워크를 사용한 빌드입니다. SEO 최적화도 가능하고 코드분할 및 라우팅에도 용이하기 때문에 현재 가장 많이 사용하는 방법이 아닐까 싶습니다. 최근 React 18 버전부터 가이드문서에서도 공식적으로 Next나 Remix 같은 프레임워크가 필요하다는 것을 인정하고 사용하는 것을 권장하는 방향으로 바뀌었습니다.

 

Start a New React Project – React

 

🐣 프로젝트 init

npx create-next-app@latest

 

🛠️ 빌드

# Dockerfile

#Next를 띄울 Node.js 베이스 이미지 선택
FROM node:20.13.1-alpine3.20

# 작업 디렉토리 설정
WORKDIR /app

# 의존성 파일 복사
COPY package.json package-lock.json ./

# 의존성 설치
RUN npm install --frozen-lockfile

# 나머지 파일 복사
COPY . .

# Next.js 애플리케이션 빌드
RUN npm run build

# 애플리케이션 실행
CMD ["npm", "start"]

# 3000번 포트 노출
EXPOSE 3000

# docker build -t nextjs-app .
# docker run -p 3000:3000 nextjs-app

 

docker build -t nextjs-app .

 

Next는 SSR(Server Side Rendering) 프레임워크 이기 때문에 Node.js 서버 위에 동작하도록 구성해야 합니다. 그래서 git에서 프로젝트도 클론 해야 되고 패키지 설치부터 빌드 및 실행 등 여러 복잡성이 존재합니다.

 

특히 많은 호스팅 업체에서 제공하고 있는 우분투 18 버전 및 Centos 7 버전에서 최신 Node.js설치가 안된다는 단점도 있습니다. (GLIBC 이슈 => https://github.com/nodejs/node/issues/43246)

 

따라서 위와같이 프로젝트 루트 경로에 Dockerfile을 하나 만들어놓고 원하는 Node.js 버전의 베이스 이미지를 도커허브에서 내려받은 후 사용하시는 것을 권장드립니다.

 

또한, 서버에서 빌드하는 경우 1년 프리티어 무료 서버의 경우 기본 용량으로 1 CPU, 1GB MEM 을 지원하는 곳(AWS, NCloud)이 많기 때문에 패키지 설치(npm install)시 과도한 메모리 사용으로 서버가 셧다운 될 수 있으므로 주의하셔야 합니다.

 

따라서 빌드하기전에 df-h free-h 등의 명령어로 서버의 용량과 메모리를 체크 후에 빌드하는 습관을 들이는 것이 좋습니다.

 

🚀 배포

docker run -d -p 3000:3000 nextjs-app

 

실행명령은 간단하게 다음과 같이 3000번 포트로 띄워서 사용하시면 됩니다. 빌드 및 배포 과정이 비교적 복잡하기 때문에 간단하게 깃허브 연동만 하면 서버를 생성해 주는 vercel, netlify, swyg 등 깃헙 연동이 가능한 여러 플랫폼 활용하는 것도 하나의 방법입니다.

 

---

 

4. Next Static Export 빌드 및 배포

Next를 정적으로 빌드 및 배포하는 방법입니다. Next 프로젝트 베이스로 개발은 하는데 동적라우팅 없이 단순한 SPA(Single Page Application)을 개발한다면 다음과 같은 방법으로도 빌드 및 배포가 가능합니다. AWS S3를 사용하는 경우에 유용합니다.

 

🐣 프로젝트 init

npx create-next-app@latest

 

🛠️ 빌드

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    appDir: true,
  },
  output: "export",
  reactStrictMode: false,
};

module.exports = nextConfig;

 

npm run build

 

빌드를 하기전에 먼저 next.config.js 파일에서 위와 같이 output: “export” 옵션을 설정해 줍니다. 이 옵션을 통해 Next를 static 하게 빌드할 수 있고 CRA 기본 템플릿을 빌드했을 때와 마찬가지로 빌드 폴더가 생성되는데 이 때는 build와. next가 아닌 out 폴더가 생성됩니다.

 

이 out 폴더안에는 index.html이 있고 CRA 기본템플릿을 빌드했을 때와 마찬가지로 정적리소스들로 구성이 되어 있기 때문에 해당 폴더를 nginx 경로에 삽입해 주시면 됩니다.

 

TMI이지만 만약 app router 방식으로 사용하는 경우에는 13.3 버전부터 static 빌드를 사용할 수 있습니다. 저도 사용하다가 out폴더가 계속 생성이 안 돼서 한참 헤맸던 것 같아서 공유드립니다.(이슈 =>  https://github.com/vercel/next.js/issues/44002)

 

🚀 배포

server {
    server_name 도메인 주소 입력;
    location / {
      root 프로젝트 경로 입력/out;
      index index.html;
      try_files $uri $uri/ =404;
    }
}

 

Next 정적리소스도 마찬가지로 다음과 같이 빌드 후 나타난 out폴더를 서버로 올린 뒤에 웹 서버(nginx) 설정 파일에 build 폴더를 연결한 뒤 서버를 재기동하시면 됩니다.

 

---

 

5. 상황에 맞는 빌드 및 배포 방법 정하기

지금까지 제가 해커톤에서 즐겨쓰는 프론트엔드 빌드 및 배포 방법을 소개해 드렸는데요. 다음은 이 다양한 빌드 방법들을 저는 어떤 식으로 사용해오고 있는지 공유해 드리도록 하겠습니다.

 

해커톤에서 사용할 수 있는 프론트엔드 빌드 및 배포방법 정리

 

저는 이와 같은 기준으로 프론트 빌드, 배포 방법을 활용하고 있습니다. 물론 이 외에도 webpack을 활용할 수도 있고 Next에도 pwa 템플릿이 있어서 이게 꼭 정답이다라고 말씀드릴 수는 없습니다만, 지금까지 참여한 여러 해커톤 및 사이드 프로젝트들 빌드 및 배포에 대해 한번쯤 정리해보고 싶었고 저는 위와 같은 방식으로 사용하고 있다는 경험을 공유해드리고 싶었습니다.

 

요즘 워낙 프론트엔드 트렌드가 빨리빨리 변화하다 보니까 내년이 되면 또 빌드 및 배포 패러다임이 어떻게 바뀔지 모르겠지만 만약 바뀌게 되더라도 그때 또다시 추가적으로 문서를 갱신해 보도록 하겠습니다. 이 글을 통해 해커톤 및 사이드프로젝트를 진행하시는 프론트엔드 엔지니어분들께 조금이나마 도움이 되었으면 좋겠습니다. 읽어주셔서 감사합니다.🙂