슬기로운 테크 블로그 생활 - 프로젝트 생성과 페이지 배포
노자의 『도덕경』에는 다음과 같은 구절이 나온다.
千里之行始於足下 (천리지행시우족불)
천 리를 가는 여정도 한 걸음부터 시작된다.
프로그래밍을 배울 때 가장 먼저 접하게 되는 문구는 아마도 'Hello World' 가 아닐까? 언어나 환경은 제각각이었어도 어떤 프로젝트이던 간에 'Hello World 출력해보기' 에 해당하는 단계는 항상 있었던 것 같다. 새로 시작한 테크 블로그 프로젝트에서도 이에 걸맞는 첫 단추가 필요하다고 생각했기에, 간단한 페이지를 인터넷 상에 띄워 보는 것을 첫 번째 목표로 하게 되었다. 이번 포스트에서는 실제로 Next.js 프로젝트를 생성하고 GitHub Action을 통해 배포하기까지의 과정을 소개한다.
개발 환경 설정하기
지난 포스트에서 Cascade의 도움을 받아 호스팅 서비스와 기술 스택을 구성하기는 했지만 여전히 내 머릿속은 백지장에 가까웠다. 일단은 실제로 개발을 시작할 수 있는 환경을 구축하는 것이 먼저라고 보고, Cascade에게 필요한 개발 환경에 대해 물어보았다. "Next.js로 블로그를 만들려면 어떤 환경 설정이 필요할까?"라는 질문에 Cascade는 다음과 같은 항목들을 알려주었다:
- Node.js와 npm: Next.js 애플리케이션을 개발하고 실행하기 위한 기본 환경
- Git: 버전 관리와 GitHub Pages 배포를 위한 필수 도구
- GitHub 계정: 프로젝트 호스팅과 GitHub Pages 설정을 위해 필요
새 도구나 패키지, 라이브러리를 설치해 본 사람이라면 이런 작업이 생각보다 골치 아프고 괴로운 것이라는 것에 동의할 것이다. Windsurf를 사용하면서 놀라웠던 점 중의 하나가 바로 이 단계를 획기적으로 도와줄 수 있다는 점이었다. 터미널 명령어를 통한 간편 설치를 지원하는 경우에는 Cascade가 알아서 터미널을 통해 설치를 실행했고, 그게 어려운 경우에는 다운로드 링크와 함께 설치 과정을 단계별로 안내 받을 수 있었다. 설치 과정에서 발생할 수 있는 오류나 문제점에 대한 해결책 또한 쉽게 얻을 수 있다. 예를 들어, Node.js 버전 호환성 문제나 Git 설정 시 주의사항 등을 사전에 안내받아 문제를 예방할 수 있었다.
설치를 완료하고 터미널에서 버전을 확인해보니 모두 최신 버전으로 잘 설치되어 있었다:
이제 프로젝트를 생성할 준비가 되었다.
프로젝트 생성하기
테크 블로그를 위한 Next.js 프로젝트를 생성하는 것부터 시작해보자. Next.js는 공식적으로 create-next-app 명령어를 통해 새 프로젝트를 손쉽게 생성할 수 있다.
이 명령어를 실행하면 몇 가지 설정 옵션을 선택할 수 있다:
✔ Would you like to use TypeScript? … Yes
✔ Would you like to use ESLint? … Yes
✔ Would you like to use Tailwind CSS? … Yes
✔ Would you like to use `src/` directory? … Yes
✔ Would you like to use App Router? … Yes
✔ Would you like to customize the default import alias? … No
TypeScript, ESLint, Tailwind CSS, src 디렉토리, App Router를 모두 사용하기로 선택했다. 이렇게 하면 프로젝트의 기본 구조가 생성된다.
프로젝트 구조 살펴보기
생성된 프로젝트의 기본 구조는 다음과 같다:
이 기본 구조를 테크 블로그에 맞게 확장해 나갈 것이다. 먼저, 블로그 포스트를 관리하기 위한 구조를 추가해보자.
MDX 설정하기
Next.js에서 MDX를 사용하기 위해서는 추가적인 패키지 설치가 필요하다.
그리고 next.config.js 파일을 수정하여 MDX 파일을 처리할 수 있도록 설정한다:
const withMDX = require('@next/mdx')({
extension: /\.mdx?$/,
options: {
remarkPlugins: [],
rehypePlugins: [],
},
});
/** @type {import('next').NextConfig} */
const nextConfig = {
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
};
module.exports = withMDX(nextConfig);
블로그 포스트 구조 만들기
블로그 포스트를 관리하기 위한 디렉토리 구조를 만들어보자. src/content/posts 디렉토리를 생성하여 모든 블로그 포스트를 이곳에 저장할 것이다.
이제 첫 번째 블로그 포스트 파일을 생성해보자:
블로그 포스트 메타데이터 관리
각 블로그 포스트는 제목, 설명, 날짜, 태그 등의 메타데이터를 포함해야 한다. 이를 위해 TypeScript 타입을 정의해보자. src/types/post.ts 파일을 생성한다:
export interface PostMetadata {
title: string;
description: string;
date: string;
datetime: string;
tags: string[];
published: boolean;
series?: {
name: string;
order: number;
};
}
Git 저장소 설정하기
이제 프로젝트를 GitHub에 올릴 준비를 해보자. 먼저, GitHub에서 새 저장소를 생성한다. 저장소 이름은 username.github.io 형식으로 지정해야 GitHub Pages를 사용할 수 있다. 내 경우에는 admelioradev.github.io로 설정했다.
저장소를 생성한 후, 로컬 프로젝트를 이 저장소에 연결한다:
GitHub Pages 배포 설정
GitHub Pages를 사용하여 Next.js 프로젝트를 배포하기 위해서는 몇 가지 추가 설정이 필요하다. Next.js는 기본적으로 서버 사이드 렌더링을 지원하지만, GitHub Pages는 정적 파일만 호스팅할 수 있다. 따라서 Next.js 프로젝트를 정적 사이트로 내보내는 설정이 필요하다.
next.config.js 파일을 다음과 같이 수정한다:
const withMDX = require('@next/mdx')({
extension: /\.mdx?$/,
options: {
remarkPlugins: [],
rehypePlugins: [],
},
});
/** @type {import('next').NextConfig} */
const nextConfig = {
pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
output: 'export',
images: {
unoptimized: true,
},
basePath: '',
assetPrefix: '',
};
module.exports = withMDX(nextConfig);
여기서 output: 'export'는 Next.js 프로젝트를 정적 HTML 파일로 내보내도록 설정한다. images: { unoptimized: true }는 Next.js의 이미지 최적화 기능을 비활성화하는데, 이는 정적 내보내기에서 필요한 설정이다.
GitHub Actions 워크플로우 설정
GitHub Actions를 사용하여 자동 배포 파이프라인을 설정해보자. .github/workflows 디렉토리를 생성하고 deploy.yml 파일을 추가한다:
deploy.yml 파일에 다음 내용을 추가한다:
name: Deploy to GitHub Pages
on:
push:
branches: [main]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: out
branch: gh-pages
이 워크플로우는 main 브랜치에 푸시가 발생할 때마다 실행된다. Node.js 환경을 설정하고, 의존성을 설치하고, 프로젝트를 빌드한 다음, 빌드된 파일을 gh-pages 브랜치에 배포한다.
package.json 스크립트 수정
package.json 파일의 스크립트 섹션을 다음과 같이 수정한다:
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint"
}
첫 배포 확인하기
이제 모든 설정이 완료되었으니, 변경 사항을 커밋하고 GitHub에 푸시해보자:
GitHub 저장소의 Actions 탭에서 워크플로우가 실행되는 것을 확인할 수 있다. 워크플로우가 성공적으로 완료되면, https://admelioradev.github.io에서 배포된 블로그를 확인할 수 있다.
커스텀 도메인 설정 (선택 사항)
GitHub Pages에서 커스텀 도메인을 사용하고 싶다면, 다음 단계를 따르면 된다:
- 도메인 제공업체에서 도메인을 구매한다.
- GitHub 저장소의 Settings > Pages에서 Custom domain 섹션에 도메인을 입력한다.
- 도메인 제공업체의 DNS 설정에서 GitHub Pages를 가리키는 CNAME 레코드를 추가한다.
CNAME www username.github.io
또한, 저장소에 public/CNAME 파일을 생성하고 도메인 이름을 입력한다:
www.yourdomain.com
결론
이번 포스트에서는 Next.js 프로젝트를 생성하고, MDX를 설정하고, GitHub Pages에 배포하는 과정을 살펴보았다. 이제 기본적인 블로그 구조가 갖춰졌으니, 다음 포스트에서는 테마 시스템을 구현하여 다크 모드와 라이트 모드를 지원하는 방법에 대해 알아볼 예정이다.
다음 포스트에서는 테마 시스템 구현에 대해 자세히 다룰 예정이다. 테마 전환 기능, 사용자 선호도 저장, 시스템 설정 감지 등 다양한 기능을 구현하는 방법을 알아보자.