Blog

프로젝트 소개 및 목표

React + Node.js 풀스택 앱 배포하기는 현대 웹 개발의 핵심 기술을 모두 경험할 수 있는 실전 프로젝트입니다. 프론트엔드부터 백엔드, 데이터베이스 연동, 그리고 실제 배포까지 전 과정을 다루며, 포트폴리오에 추가할 수 있는 완성도 높은 결과물을 만들 수 있습니다. 이 가이드를 통해 REST API 개발, 상태 관리, 데이터베이스 설계, 클라우드 배포 등 실무에서 바로 활용 가능한 스킬을 습득하게 됩니다. 단순한 튜토리얼을 넘어서 실제 서비스 개발 프로세스를 경험하며, 개발자로서의 역량을 한 단계 끌어올릴 수 있습니다.

필요한 기술 스택

이 프로젝트를 완성하기 위해서는 다음과 같은 기술 스택이 필요합니다. 프론트엔드는 React 18, React Router, Axios, TailwindCSS를 사용하며, 백엔드는 Node.js, Express.js, JWT 인증을 구현합니다. 데이터베이스는 MongoDB 또는 PostgreSQL 중 선택 가능하며, 배포 환경으로는 프론트엔드는 Vercel 또는 Netlify, 백엔드는 Railway 또는 Render를 활용합니다. 개발 도구로는 VS Code, Postman, Git이 필요하며, 각 도구의 기본적인 사용법을 숙지하고 있으면 더욱 원활하게 진행할 수 있습니다.

프로젝트 셋업

프로젝트를 시작하기 전에 개발 환경을 구축해야 합니다. Node.js (v18 이상)와 npm 또는 yarn이 설치되어 있는지 확인하세요. 먼저 프로젝트 루트 디렉토리를 생성하고, 그 안에 client와 server 폴더를 만듭니다. 프론트엔드는 Vite를 사용하여 빠른 개발 환경을 구축하고, 백엔드는 Express 프레임워크로 RESTful API를 설계합니다. MongoDB Atlas에서 무료 클러스터를 생성하거나, PostgreSQL을 로컬 또는 클라우드에 설치합니다. Git 저장소를 초기화하여 버전 관리를 시작하며, .gitignore 파일에 node_modules, .env 등 민감한 파일을 추가합니다. 환경 변수 관리를 위해 .env 파일을 설정하고, 데이터베이스 연결 정보와 JWT 시크릿 키 등을 안전하게 보관합니다.

단계별 구현 과정

1단계: 백엔드 API 서버 구축

먼저 서버 폴더로 이동하여 프로젝트를 초기화합니다:

// server 폴더에서 실행
npm init -y
npm install express mongoose dotenv cors jsonwebtoken bcryptjs
npm install --save-dev nodemon

기본 서버 구조를 만들어봅시다. server.js 파일을 생성합니다:

const express = require('express');
const mongoose = require('mongoose');
const cors = require('cors');
require('dotenv').config();

const app = express();
const PORT = process.env.PORT || 5000;

// 미들웨어
app.use(cors());
app.use(express.json());

// 데이터베이스 연결
mongoose.connect(process.env.MONGODB_URI)
  .then(() => console.log('MongoDB 연결 성공'))
  .catch(err => console.error('MongoDB 연결 실패:', err));

// 라우트
app.get('/api/health', (req, res) => {
  res.json({ status: 'OK', message: '서버가 정상 작동 중입니다' });
});

app.listen(PORT, () => {
  console.log(`서버가 포트 ${PORT}에서 실행 중입니다`);
});

2단계: 데이터베이스 모델 설계

models/User.js 파일을 생성하여 사용자 스키마를 정의합니다:

const mongoose = require('mongoose');
const bcrypt = require('bcryptjs');

const userSchema = new mongoose.Schema({
  username: {
    type: String,
    required: true,
    unique: true,
    trim: true
  },
  email: {
    type: String,
    required: true,
    unique: true,
    lowercase: true
  },
  password: {
    type: String,
    required: true,
    minlength: 6
  },
  createdAt: {
    type: Date,
    default: Date.now
  }
});

// 비밀번호 해싱
userSchema.pre('save', async function(next) {
  if (!this.isModified('password')) return next();
  this.password = await bcrypt.hash(this.password, 12);
  next();
});

// 비밀번호 검증 메서드
userSchema.methods.comparePassword = async function(candidatePassword) {
  return await bcrypt.compare(candidatePassword, this.password);
};

module.exports = mongoose.model('User', userSchema);

3단계: 인증 API 구현

routes/auth.js 파일을 생성하여 회원가입과 로그인 기능을 구현합니다:

const express = require('express');
const jwt = require('jsonwebtoken');
const User = require('../models/User');
const router = express.Router();

// 회원가입
router.post('/register', async (req, res) => {
  try {
    const { username, email, password } = req.body;
    
    const existingUser = await User.findOne({ $or: [{ email }, { username }] });
    if (existingUser) {
      return res.status(400).json({ message: '이미 존재하는 사용자입니다' });
    }
    
    const user = new User({ username, email, password });
    await user.save();
    
    const token = jwt.sign({ userId: user._id }, process.env.JWT_SECRET, { expiresIn: '7d' });
    
    res.status(201).json({
      message: '회원가입 성공',
      token,
      user: { id: user._id, username: user.username, email: user.email }
    });
  } catch (error) {
    res.status(500).json({ message: '서버 오류', error: error.message });
  }
});

// 로그인
router.post('/login', async (req, res) => {
  try {
    const { email, password } = req.body;
    
    const user = await User.findOne({ email });
    if (!user || !(await user.comparePassword(password))) {
      return res.status(401).json({ message: '이메일 또는 비밀번호가 올바르지 않습니다' });
    }
    
    const token = jwt.sign({ userId: user._id }, process.env.JWT_SECRET, { expiresIn: '7d' });
    
    res.json({
      message: '로그인 성공',
      token,
      user: { id: user._id, username: user.username, email: user.email }
    });
  } catch (error) {
    res.status(500).json({ message: '서버 오류', error: error.message });
  }
});

module.exports = router;

4단계: 프론트엔드 React 앱 구축

클라이언트 폴더에서 Vite로 React 프로젝트를 생성합니다:

// client 폴더에서 실행
npm create vite@latest . -- --template react
npm install
npm install react-router-dom axios

src/App.jsx에서 라우팅을 설정합니다:

import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { useState, useEffect } from 'react';
import Login from './pages/Login';
import Register from './pages/Register';
import Dashboard from './pages/Dashboard';

function App() {
  const [isAuthenticated, setIsAuthenticated] = useState(false);
  
  useEffect(() => {
    const token = localStorage.getItem('token');
    setIsAuthenticated(!!token);
  }, []);
  
  return (
    
      
        } />
        } />
         : } 
        />
        } />
      
    
  );
}

export default App;

5단계: API 통신 설정

src/services/api.js 파일을 생성하여 API 통신을 관리합니다:

import axios from 'axios';

const API = axios.create({
  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:5000/api'
});

// 요청 인터셉터: 모든 요청에 토큰 추가
API.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// 응답 인터셉터: 인증 오류 처리
API.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('token');
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

export const authAPI = {
  register: (userData) => API.post('/auth/register', userData),
  login: (credentials) => API.post('/auth/login', credentials)
};

export default API;

테스트 및 배포

React + Node.js 풀스택 앱 배포하기의 마지막 단계는 테스트와 배포입니다. 먼저 로컬에서 프론트엔드와 백엔드를 동시에 실행하여 기능을 테스트합니다. Postman으로 API 엔드포인트를 검증하고, 회원가입부터 로그인, 데이터 CRUD 작업까지 모든 기능이 정상 작동하는지 확인합니다. 배포 전에 환경 변수를 점검하고, 프로덕션 빌드를 생성합니다. 백엔드는 Railway 또는 Render에 배포하며, GitHub 저장소와 연동하여 자동 배포를 설정합니다. 프론트엔드는 npm run build로 빌드한 후 Vercel 또는 Netlify에 배포하며, 환경 변수에 백엔드 API URL을 설정합니다. CORS 설정을 프로덕션 도메인에 맞게 조정하고, HTTPS를 반드시 활성화합니다. 배포 후에는 실제 환경에서 모든 기능을 재검증하며, 에러 로깅과 모니터링 도구를 설정하여 안정적인 서비스를 유지합니다.

마무리 및 확장 아이디어

이제 완성된 React + Node.js 풀스택 앱 배포하기 프로젝트를 더욱 발전시킬 수 있습니다. 소셜 로그인(Google, GitHub OAuth) 통합, 프로필 이미지 업로드 기능, 실시간 알림 시스템(Socket.io), 페이지네이션과 검색 필터, 반응형 디자인 개선 등을 추가할 수 있습니다. Redux 또는 Zustand로 상태 관리를 고도화하고, Jest와 React Testing Library로 테스트 코드를 작성하면 더욱 견고한 애플리케이션이 됩니다. CI/CD 파이프라인을 구축하여 자동화된 배포 프로세스를 만들고, Docker로 컨테이너화하면 확장성과 유지보수성이 크게 향상됩니다. 이 프로젝트는 포트폴리오의 핵심 작품이 될 것이며, 실무 역량을 증명하는 강력한 자산이 됩니다.