2편. GraphQL 서버 개발 환경 구축 (Node.js + TS)
📚 목차
1. 개발 환경 준비 및 TypeScript 기반 프로젝트 초기화
2. GraphQL Yoga 및 관련 패키지 설치
3. ESLint, Prettier, Dev script 구성(ESLint 9.x + Flat Config)
4. 환경 변수 설정(.env 구성)
✔ 마무리 - GraphQL 서버 개발 환경 요약
1. 개발 환경 준비 및 TypeScript 기반 프로젝트 초기화
GraphQL 서버를 안정적으로 개발하기 위해서는 Node.js 런타임과 VS Code를 먼저 준비하고, TypeScript 기반의 프로젝트 구조를 초기화해야 합니다.
🟦 1) Node.js (v18 이상 권장)
GraphQL 백엔드 서버를 만들기 위해서는 먼저 Node.js를 설치해야 합니다. Node.js는 자바스크립트로 백엔드 애플리케이션을 실행할 수 있게 해주는 런타임 환경이며, GraphQL 서버, Fastify, Prisma 등 대부분의 도구들이 Node.js 기반으로 동작합니다.
✔️ 설치 방법
1. Node.js 공식 사이트에 접속합니다.
2. 다운로드 페이지에는 두 가지 버전이 보이는데, "LTS (Long-Term Support)" 버전을 선택하는 것을 추천합니다.
LTS 버전은 안정성과 호환성이 검증되어, 대부분의 프로젝트에서 기본으로 사용됩니다.
3. 운영체제에 맞는 설치 파일을 다운로드한 후, 설치 마법사 안내에 따라 설치를 진행합니다.
특별한 설정 없이 기본 옵션으로 설치하면 충분합니다.
설치 후 터미널(Windows PowerShell, Linux Terminal 등)에서 아래 명령으로 버전을 확인합니다.
node -v # 예: v22.17.0
npm -v # 예: 10.8.3
npx -v # 예: 10.8.3▸ node : Node.js 런타임
▸ npm : 패키지 관리 도구
▸ npx : 패키지 실행 도구
🟦 2) VS Code (Visual Studio Code)
GraphQL 서버 개발을 위한 코드 편집기 중에서 가장 널리 사용되는 도구는 VS Code(Visual Studio Code)입니다.
마이크로소프트에서 무료로 제공하는 이 에디터는 빠른 속도, 풍부한 확장 기능, 직관적인 인터페이스 덕분에 초보자부터 전문가까지 폭넓게 사랑받고 있습니다.
✔️ 설치 방법
1. 아래 공식 웹사이트에 접속합니다:
https://code.visualstudio.com/download/
2. 운영체제에 맞는 버전을 다운로드해 설치합니다.
3. 설치가 완료되면 바탕화면 또는 시작 메뉴에서 Visual Studio Code를 실행합니다.
✔️ 확장 플러그인 설치
1. VS Code를 실행합니다.
2. 왼쪽 사이드바에서 확장(Extensions) 아이콘을 클릭합니다. (또는 단축키 Ctrl + Shift + X)
3. 각각의 확장 플러그인 이름을 검색한 뒤 [설치] 버튼을 클릭하면 끝입니다:
🔸ESLint – 코드 문법 검사기
JavaScript 또는 TypeScript 코드에서 오타나 잘못된 문법을 자동으로 탐지합니다.
실시간으로 빨간 줄 표시와 함께 문제가 되는 부분을 알려줍니다.
🔸Prettier - Code Formatter – 코드 포맷 자동 정리
코드 스타일을 자동으로 정리해 주는 도구입니다.
파일 저장 시 들여쓰기, 세미콜론, 따옴표 등 스타일을 통일된 형식으로 자동 정렬해 줍니다.
🔸GraphQL – 스키마 지원 및 쿼리 자동 완성
.graphql 또는 .gql 파일에서 자동 완성, 스키마 인식, 문법 강조 기능을 제공합니다.
백엔드와 프론트엔드 모두에서 GraphQL 쿼리 작성 시 매우 유용합니다.
🟦 3) 프로젝트 생성 및 초기화
프로젝트용 디렉토리를 다음과 같이 생성합니다.
mkdir ~/graphql-tutorial-server
cd ~/graphql-tutorial-server
# 프로젝트 초기화
# VSCode 실행 후 TERMINAL에서 실행해도 됩니다.
npm init -ynpm init -y는 기본 설정을 자동 적용하여 package.json 파일을 생성합니다.
이후 graphql-tutorial-server 폴더 안에는 다음과 같은 기본 구조가 생성됩니다:
graphql-tutorial-server/
├── package.json
#package.json 예시
{
"name": "graphql-tutorial-server",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": ""
}
🟦 4) TypeScript 개발 환경 설치
TypeScript 및 실행을 위한 관련 개발 의존성을 설치합니다
npm install --save-dev typescript ts-node @types/node> 결과 예시
added 20 packages, and audited 21 packages in 4s
found 0 vulnerabilities
> npm list
graphql-tutorial-server@1.0.0 D:\GraphQL\graphql-tutorial-server
├── @types/node@24.1.0
├── ts-node@10.9.2
└── typescript@5.8.3▸ typescript: TypeScript 컴파일러
▸ ts-node: TypeScript 파일 직접 실행
▸ @types/node: Node.js API 타입 정의
🟦 5) tsconfig.json 생성 및 설정
TypeScript 설정 파일인 tsconfig.json은 프로젝트의 컴파일 방식과 경로 구조, 타입 검사 수준 등을 정의하는 핵심 구성 파일입니다.
다음 명령어를 실행하면 현재 디렉토리에 이 설정 파일이 자동으로 생성됩니다
npx tsc --init▸npx : 프로젝트나 글로벌에 설치된 패키지를 실행하는 도구
▸tsc : TypeScript 컴파일러(TypeScript Compiler) 실행 명령어
▸--init : 설정 파일(tsconfig.json)을 생성하라는 옵션
이후, 생성된 tsconfig.json 파일을 아래와 같이 수정합니다:
{
"compilerOptions": {
// 컴파일된 JavaScript의 대상 버전 (ES2016 이상이면 async/await 등 사용 가능)
"target": "es2016",
// Node.js 환경에서 일반적으로 사용하는 CommonJS 모듈 시스템
"module": "commonjs",
// 컴파일된 결과물이 저장될 디렉토리 (ts → js)
"outDir": "dist",
// 소스 파일이 위치한 루트 디렉토리
"rootDir": "src",
// CommonJS 방식의 모듈(import/export)을 ESModule처럼 사용할 수 있도록 호환
"esModuleInterop": true,
// 엄격한 타입 검사 활성화 (noImplicitAny, strictNullChecks 등 포함)
"strict": true,
// 외부 타입 정의 파일(@types/...)의 타입 검사 생략 → 컴파일 속도 향상
"skipLibCheck": true
},
// TypeScript가 컴파일할 파일들을 명시적으로 지정 (src 디렉토리만 포함)
"include": ["src"],
// 컴파일에서 제외할 디렉토리 지정 (node_modules는 기본 제외되지만 명시적으로 추가)
"exclude": ["node_modules"]
}
🟦 6) src 디렉토리 생성
모든 소스 코드는 src/ 디렉토리 내부에 작성합니다. 다음 명령어로 디렉토리와 초기 파일을 생성합니다.
mkdir src
src/index.ts #파일 생성이제 src/index.ts 파일을 기반으로 GraphQL 서버의 진입점을 구성할 준비가 완료되었습니다.
이 구조는 이후에 Resolver, Schema, Context 등을 디렉토리별로 모듈화 하고 확장할 때에도 유연하게 활용할 수 있습니다.
2. GraphQL Yoga 및 관련 패키지 설치
GraphQL 서버의 핵심 기능을 구현하기 위해, 먼저 필요한 패키지를 설치하고 간단한 "Hello Query"를 실행해 보는 초기 구조를 구성합니다
🟦 1) GraphQL 관련 패키지 설치
GraphQL 서버를 구현하기 위해 기본적으로 다음 두 가지 패키지가 필요합니다.
🔸 graphql: GraphQL 스펙을 공식적으로 구현한 핵심 라이브러리로, 모든 GraphQL 서버의 기반이 됩니다.
🔸 graphql-yoga: GraphQL 서버를 쉽고 빠르게 구축할 수 있도록 도와주는 경량 프레임워크입니다.
아래 명령어로 패키지를 설치합니다
npm install graphql graphql-yoga
설치결과
PS D:\GraphQL\graphql-tutorial-server> npm list
graphql-tutorial-server@1.0.0 D:\GraphQL\graphql-tutorial-server
├── @types/node@24.1.0
├── graphql-yoga@5.15.1
├── graphql@16.11.0
├── ts-node@10.9.2
└── typescript@5.8.3graphql-yoga는 Apollo Server와 유사한 방식으로 작동하며, 프로젝트 초기에는 빠르고 직관적인 서버 실행 구조를 제공하는 장점이 있습니다.
🟦 2) 기본 서버 코드 – src/index.ts
이제 src/index.ts 파일을 생성하고, 다음과 같이 가장 간단한 GraphQL 서버를 구현합니다.
GraphQL Yoga v5에서는 다음과 같이 기본 default export 방식으로 사용해야 합니다:
// src/index.ts
import { createYoga } from 'graphql-yoga'
import { createServer } from 'http'
import { createSchema } from 'graphql-yoga'
const yoga = createYoga({
schema: createSchema({
typeDefs: /* GraphQL */ `
type Query {
hello: String!
}
`,
resolvers: {
Query: {
hello: () => 'Hello, GraphQL!',
},
},
}),
})
const server = createServer(yoga)
server.listen(4000, () => {
console.log('GraphQL Server running at http://localhost:4000/graphql')
})▸ typeDefs : GraphQL API의 구조(쿼리 타입 등)를 정의
▸ resolvers : 클라이언트의 쿼리 요청을 처리하고 실제 데이터를 반환
▸ createYoga : GraphQL 서버 생성 함수
▸ createServer : HTTP 서버 생성 (Node.js 내장)
▸ server.listen(4000) : 서버를 4000번 포트에서 실행
🟦 3) 서버 실행 및 테스트
작성한 GraphQL 서버 코드를 실행하려면 다음 명령어를 사용합니다:
npx ts-node src/index.ts▸ npx : 패키지를 즉시 실행할 수 있도록 도와주는 도구
▸ ts-node : ts-node가 전역(global)으로 설치되어 있지 않아도, node_modules/.bin/ts-node를 자동으로 찾아 실행해 줍니다.
▸ src/index.ts : 실행할 대상 TypeScript 파일입니다.
정상적으로 실행되면 다음과 같은 메시지를 확인할 수 있습니다.
GraphQL Server running at http://localhost:4000/graphql브라우저에서 해당 주소로 접속(ex: http://localhost:4000/graphql)하면 GraphiQL 인터페이스가 나타나며, 다음 쿼리를 실행해 결과를 확인할 수 있습니다
query {
hello
}
결과예시
{
"data": {
"hello": "Hello, GraphQL!"
}
}
3. ESLint, Prettier, Dev script 구성(ESLint 9.x + Flat Config)
GraphQL 서버 개발에서 코드 스타일의 일관성 유지와 잠재적 오류 사전 방지는 협업과 유지보수의 핵심입니다.
이를 위해
🔸ESLint는 정적 분석을 통해 문법 오류와 버그 가능성을 탐지하고,
🔸Prettier는 코드 포맷팅을 자동화합니다.
ESLint 9.x 이상부터는 기존 .eslintrc.* 형식 대신 Flat Config (eslint.config.mjs)를 공식 권장합니다.
Flat Config는 배열 기반 모듈 구성 방식으로, 설정의 가독성과 확장성이 향상되었습니다.
🟦 1) 필요한 패키지 설치
아래 명령으로 ESLint, Prettier, TypeScript 관련 플러그인들을 한 번에 설치합니다.
# ESLint + TypeScript 관련 패키지
npm install --save-dev eslint @eslint/js
npm install --save-dev typescript-eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
# Prettier 연동 관련 패키지
npm install --save-dev prettier eslint-plugin-prettier eslint-config-prettier▸ eslint : 정적 코드 분석 도구 (기본 엔진)
▸ @eslint/js : ESLint 기본 규칙 세트 (Flat Config용)
▸ @typescript-eslint/parser : TypeScript 코드 파서
▸ @typescript-eslint/eslint-plugin : TypeScript 린트 규칙 모음
▸ prettier : 코드 자동 포맷터
▸ eslint-plugin-prettier : Prettier 오류를 ESLint로 표시 (선택)
▸ eslint-config-prettier : Prettier와 충돌하는 ESLint 규칙 비활성화
참고: eslint-plugin-prettier는 필수는 아니며, Prettier 포맷팅 오류를 ESLint에서 에러로 보고하고 싶을 때만 사용합니다.
🟦 2) Flat Config 설정 – eslint.config.mjs
프로젝트 루트에 eslint.config.mjs 파일을 생성하고 아래와 같이 작성합니다.
// eslint.config.js
// ESLint에서 제공하는 JavaScript 기본 규칙 세트를 불러옴
import js from '@eslint/js';
// TypeScript 코드를 ESLint로 분석하기 위해 typescript-eslint 모듈을 불러옴
// 여기에는 parser, plugin, 추천 규칙 세트 등이 포함됨
import tseslint from 'typescript-eslint';
// Prettier 포맷팅 규칙을 ESLint와 연동하기 위해 Prettier 플러그인을 불러옴
import prettierPlugin from 'eslint-plugin-prettier';
// Prettier와 충돌하는 ESLint 규칙을 비활성화하기 위한 설정
// (예: 세미콜론, 따옴표 관련 규칙 충돌 방지)
import prettierConfig from 'eslint-config-prettier';
// typescript-eslint에서 제공하는 TypeScript 추천 규칙 세트를 가져옴
// await를 쓰는 이유: typescript-eslint.configs.recommended는 비동기 함수 반환
const ts = await tseslint.configs.recommended;
export default [
// ================================
// 1. ESLint 무시(ignore) 설정
// - 특정 폴더나 파일은 린트 검사에서 제외
// - 가장 상위에 위치시켜 전역적으로 적용
// ================================
{
ignores: ['dist/', 'node_modules/', 'coverage/'],
},
// ================================
// 2. JavaScript 기본 규칙 적용
// - @eslint/js에서 제공하는 권장 규칙
// ================================
js.configs.recommended,
// ================================
// 3. TypeScript 추천 규칙 적용
// - typescript-eslint에서 제공하는 권장 규칙 세트
// - 타입 검사를 하지 않는 "기본 모드"의 규칙들이 포함
// ================================
...ts,
// ================================
// 4. Prettier와 충돌하는 ESLint 포맷팅 규칙 비활성화
// - eslint-config-prettier를 가장 마지막에 위치시켜야
// 앞서 적용한 규칙들 중 포맷팅 관련 충돌을 해제 가능
// ================================
prettierConfig,
// ================================
// 5. TypeScript 파일에만 적용할 규칙/설정
// - 확장자가 .ts인 파일을 대상으로만 동작
// ================================
{
files: ['**/*.ts'], // 프로젝트 전체에서 모든 .ts 파일 적용
languageOptions: {
// TypeScript 코드를 파싱하기 위해 @typescript-eslint/parser 사용
parser: tseslint.parser,
parserOptions: {
ecmaVersion: 'latest', // 최신 ECMAScript 문법 지원
sourceType: 'module', // ES Modules(import/export) 문법 사용
// [옵션] 타입 기반 린팅 활성화
// project: true → 현재 디렉토리의 tsconfig.json 자동 탐색
// project: ['./tsconfig.json'] → 경로를 명시적으로 지정
// 활성화 시 타입 정보를 기반으로 더 정밀한 규칙 검사 가능
// 단, 성능 저하가 있을 수 있으므로 CI나 빌드 시에만 사용 권장
// project: true, // 또는 ['tsconfig.json']
},
},
plugins: {
// Prettier 플러그인을 ESLint에 등록
prettier: prettierPlugin,
},
rules: {
// Prettier 포맷팅 규칙을 ESLint 에러로 처리
// .prettierrc 파일의 설정(singleQuote, semi 등)과 일치시켜야 함
'prettier/prettier': ['error', { singleQuote: true, semi: true }],
// Prettier가 관리하는 포맷팅 규칙은 ESLint에서 비활성화하여 충돌 방지
// (예: semi, quotes 등의 규칙)
},
},
];
🟦 3) Prettier 포맷 설정 – .prettierrc
Prettier의 세부 포맷 옵션을 .prettierrc 또는 prettier.config.js 파일로 작성할 수 있으나, 대부분의 프로젝트에서는 동적 설정이 필요하지 않고, JSON 기반의 간결한 구성이 더 직관적이기 때문에 .prettierrc 사용을 권장합니다.
{
// 줄 끝에 세미콜론을 항상 붙입니다.
"semi": true,
// 문자열은 작은따옴표(')를 사용합니다.
"singleQuote": true,
// 들여쓰기를 2칸으로 설정합니다.
"tabWidth": 2,
// ES5 문법에서 허용된 곳에는 쉼표를 붙입니다. (예: 객체/배열 마지막 요소 뒤)
"trailingComma": "es5",
// 한 줄 최대 길이를 100자로 제한합니다. 초과 시 줄바꿈됩니다.
"printWidth": 100,
// 개행문자 지정: Linux 서버(배포 환경)의 표준 개행이 LF
"endOfLine": "lf"
}
🟦 4) ESLint 무시 설정 – ignores
Flat Config에서는 .eslintignore 대신 eslint.config.js 안에서 ignores 배열을 사용합니다.
반드시 배열의 가장 상단에 위치해야 전역 무시 설정이 적용됩니다:
// eslint.config.js (일부)
export default [
{
// 이 객체는 배열의 가장 앞에 위치하여 전역적으로 적용됩니다.
ignores: ['dist/', 'node_modules/', 'coverage/'],
},
// ... (다른 설정들)
];.prettierrc는 JSON 형식이 기본이며, .js, .cjs, .yaml 등 다양한 형식도 지원합니다.
🟦 5) package.json 설정 – lint 스크립트
package.json의 scripts 항목에 lint 명령어를 추가하여 손쉽게 실행할 수 있도록 합니다.
// package.json (일부)
{
"name": "graphql-tutorial-server",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"dev": "ts-node src/index.ts",
"lint": "eslint \"src/**/*.{ts,tsx}\" --fix"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"devDependencies": {
"@eslint/js": "^9.32.0",
"@types/node": "^24.1.0",
"@typescript-eslint/eslint-plugin": "^8.38.0",
"@typescript-eslint/parser": "^8.38.0",
"eslint": "^9.32.0",
"eslint-config-prettier": "^10.1.8",
"eslint-plugin-prettier": "^5.5.3",
"globals": "^16.3.0",
"prettier": "^3.6.2",
"ts-node": "^10.9.2",
"typescript": "^5.8.3",
"typescript-eslint": "^8.38.0"
},
"dependencies": {
"graphql": "^16.11.0",
"graphql-yoga": "^5.15.1"
}
}▸ npm run lint: 코드 전체를 검사하고 자동 수정 가능 항목을 고칩니다.
▸ npm run dev: GraphQL 서버를 개발 모드로 실행합니다
필요시 이후에 "build" 또는 "start" 명령어도 추가하실 수 있습니다.
4. 환경 변수 설정 (.env 구성)
프로젝트의 실행 포트, 데이터베이스 연결 정보, API 키 등 환경별로 달라질 수 있는 설정값은 코드에 직접 하드코딩하지 않고 .env 파일로 분리해 관리하는 것이 안전하고 효율적입니다.
🟦 1) dotenv 설치
Node.js에서 .env 파일을 읽어 환경 변수로 사용할 수 있도록 dotenv 패키지를 설치합니다.
npm install dotenv
🟦 2) .env 파일 생성
프로젝트 루트 디렉토리에 .env 파일을 생성합니다.
예시- .env
PORT=4000변수명은 대문자 + 언더스코어(_) 규칙을 따르는 것이 일반적입니다.
민감한 값(DB 비밀번호, API 키 등)은 반드시 .env에 넣고 eslint.config.mjs 파일의 ignores항목에 .env를 추가해야 합니다.
🟦 3) .env 파일 적용
dotenv 패키지를 불러오면 .env에 정의된 변수를 process.env에서 바로 사용할 수 있습니다.
src/index.ts 예시
import 'dotenv/config';
const PORT = process.env.PORT || 4000;
server.listen(PORT, () => {
console.log(`Server running at http://localhost:${PORT}/graphql`);
});.env에 PORT 값이 없으면 기본값(4000)으로 서버가 실행됩니다.
dotenv/config를 import 하는 방식은 추가 설정 없이 간단히 사용할 수 있습니다.
✔ 마무리 - GraphQL 서버 개발 환경 요약
✔️패키지 설치 명령어 요약
#TypeScript 개발 환경 설정
npm install --save-dev typescript ts-node @types/node
#GraphQL 서버 구성 (GraphQL Yoga 기반)
npm install graphql graphql-yoga
# ESLint + TypeScript 관련 패키지
npm install --save-dev eslint @eslint/js
npm install --save-dev typescript-eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
# Prettier 연동 관련 패키지
npm install --save-dev prettier eslint-plugin-prettier eslint-config-prettier
# 환경변수 설정 패키지
npm install dotenv
✔️설치 후 생성해야 할 설정 파일 목록
tsconfig.json TypeScript 컴파일 설정
eslint.config.mjs ESLint 설정
.prettierrc Prettier 포맷팅 설정
✔️ 설치된 주요 패키지
graphql-tutorial-server@1.0.0 D:\GraphQL\graphql-tutorial-server
├── @eslint/js@9.32.0
├── @types/node@24.1.0
├── @typescript-eslint/eslint-plugin@8.38.0
├── @typescript-eslint/parser@8.38.0
├── dotenv@17.2.1
├── eslint-config-prettier@10.1.8
├── eslint-plugin-prettier@5.5.3
├── eslint@9.32.0
├── globals@16.3.0
├── graphql-yoga@5.15.1
├── graphql@16.11.0
├── prettier@3.6.2
├── ts-node@10.9.2
├── typescript-eslint@8.38.0
└── typescript@5.8.3지금까지 graphql-tutorial-server 프로젝트를 기반으로, GraphQL 서버 개발을 위한 기초 환경을 하나씩 직접 구성해 보았습니다.
Node.js와 TypeScript를 바탕으로 프로젝트를 초기화하고, ts-node로 서버를 실행하며, ESLint와 Prettier로 코드 품질을 자동으로 유지할 수 있는 실무 수준의 개발 기반을 마련한 것입니다.
※ 게시된 글 및 이미지 중 일부는 AI 도구의 도움을 받아 생성되거나 다듬어졌습니다.
'3.SW개발 > GraphQL 배우기' 카테고리의 다른 글
| 6편. GraphQL Scalar 타입 완전 정복 (0) | 2025.11.30 |
|---|---|
| 5편. GraphQL 스키마와 리졸버 구조 이해 (0) | 2025.11.30 |
| 4편. GraphQL 실무 아키텍처 설계: 도메인 구조와 책임 분리 (0) | 2025.11.27 |
| 3편. GraphQL Hello Query 실습: 첫 서버 구축하기 (0) | 2025.11.27 |
| 1편. GraphQL이 필요한 이유: REST와의 차이 완벽 이해 (0) | 2025.11.25 |