React와 esbuild를 사용한 SSR에 대한 간단한 접근 방식

이 블로그에서는 React의 최신 기능을 활용하여 최소한의 도구와 프레임워크로 가볍고 유연한 React 애플리케이션을 만드는 방법을 살펴봅니다. Next.js 및 Remix와 같은 프레임워크는 다양한 사용 사례에 탁월하지만 이 가이드는 유사한 기능을 유지하면서 모든 권한을 갖는 데 관심이 있는 사람들을 위한 것입니다.

React 19가 출시되고 SSR을 지원하는 새로운 기능을 사용하면서 최소한의 도구를 사용하여 SSR을 지원하는 React 애플리케이션을 만드는 실험을 하기로 결정했습니다. 먼저 고려해야 할 Next.js가 제공하는 필수 기능을 살펴보겠습니다.

Feature	Next.js
SSR (Server-Side Rendering)	Built-in with minimal setup.
SSG (Static Site Generation)	Built-in with getStaticProps.
Routing	File-based routing.
Code Splitting	Automatic.
Image Optimization	Built-in with next/image.
Performance Optimizations	Automatic (e.g., prefetching, critical CSS).
SEO	Built-in tools like next/head.

이러한 기능을 기반으로 최소한의 설정을 만들 예정입니다. 단계별 가이드는 다음과 같습니다.

목차

• 설정
• esbuild 구성
• 익스프레스 앱 및 라우팅
• 리액트 앱
• 달려
• 다음 단계
• 참고자료

참고: 내 저장소 https://github.com/willyelm/react-app에서 이 튜토리얼의 내용을 찾을 수 있습니다

설정

설정의 전제 조건으로 Node.js를 설치하고 다음 패키지가 필요합니다.

• react: 구성 요소 기반의 대화형 UI 라이브러리.
• react-dom: React 기능으로 SSR 콘텐츠에 수분을 공급합니다.
• react-router-dom: React로 경로를 처리합니다.
• express: 정적 및 REST API를 위한 Node.js 단순 서버.
• esbuild: TypeScript를 트랜스파일하고 JS, CSS, SVG 및 기타 파일을 번들로 묶습니다.
• typescript: 소스 코드에 타이핑 추가

우리 설정은 정적 파일, 공개 파일 및 REST API를 제공하기 위해 Express를 사용한 라우팅을 처리합니다. 그런 다음 React-Router-dom을 사용하여 모든 요청을 처리합니다. 브라우저에 로드되면 클라이언트 번들이 사전 렌더링된 콘텐츠를 수화하고 구성 요소를 대화형으로 만듭니다. 다음은 이 아이디어를 다이어그램으로 나타낸 것입니다.

다이어그램은 Express 앱이 서버에서 React 구성 요소를 사전 렌더링하고 HTML을 반환하여 요청을 처리하는 방법을 보여줍니다. 클라이언트 측에서 React는 이러한 사전 렌더링된 구성 요소를 수화하여 상호 작용을 활성화합니다.

이 다이어그램을 염두에 두고 폴더 구조를 만들어 보겠습니다.

react-app/             # This will be our workspace directory.
  - public/            
  - scripts/           
    - build.js         # Bundle our server and client scripts.
    - config.js        # esbuild config to bundle.
    - dev.js           # Bundle on watch mode and run server.
  - src/
    - App/             # Our components will be here.
      - App.tsx        # The main application with browser routing.
      - Home.tsx.      # Our default page component.
      - NotFound.tsx   # Fallback page for unmatched routes.
    - index.tsx        # Hydrate our pre-rendered client app.
    - main.tsx         # Server app with SSR components.
    - style.css        # Initial stylesheet.   
  package.json
  tsconfig.json

종속성을 추가하고 package.json을 설정해 보겠습니다.

{
  "name": "react-app",
  "type": "module",
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/node": "^22.10.2",
    "@types/react": "^19.0.2",
    "@types/react-dom": "^19.0.2",
    "esbuild": "^0.24.2",
    "typescript": "^5.7.2"
  },
  "dependencies": {
    "express": "^4.21.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "react-router-dom": "^7.1.0"
  },
  "scripts": {
    "build": "node scripts/build",
    "dev": "node scripts/dev",
    "start": "node dist/main.js"
  }
}

참고: node.js가 ESM 스크립트를 실행하려면 "type": "module" 속성이 필요합니다.

Typescript를 사용할 것이므로 tsconfig.json 파일을 구성하겠습니다.

{
  "compilerOptions": {
    "esModuleInterop": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "lib": ["DOM", "DOM.Iterable", "ES2022"],
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "baseUrl": ".",
    "paths": {
      "src": [
        "./src/"
      ]
    }
  },
  "include": [
    "src"
  ],
  "exclude": [
    "node_modules"
  ]
}

esbuild 구성

왜 esbuild인가요? 다른 도구에 비해 esbuild는 작업을 최소화하고 매우 빠르며(현재 가장 빠른 번들러) 기본적으로 typescript와 esm을 지원합니다.

이 설정에서는 esbuild를 사용하여 개발 및 빌드 스크립트를 생성하고 클라이언트 및 서버 번들을 모두 트랜스파일합니다. 이 섹션에서는 작업 공간의 스크립트 폴더에서 작업합니다.

scripts/config.js: 이 파일에는 스크립트용으로 공유될 클라이언트 및 서버 번들의 기본 구성이 포함됩니다.

import path from 'node:path';
// Working dir
const workspace = process.cwd();
// Server bundle configuration
export const serverConfig = {
  bundle: true,
  platform: 'node', 
  format: 'esm',        // Support esm packages
  packages: 'external', // Omit node packages from our node bundle
  logLevel: 'error',
  sourcemap: 'external',
  entryPoints: {
    main: path.join(workspace, 'src', 'main.tsx') // Express app
  },
  tsconfig: path.join(workspace, 'tsconfig.json'),
  outdir: path.join(workspace, 'dist')
};

// Client bundle configuration
export const clientConfig = {
  bundle: true,
  platform: 'browser',
  format: 'esm',
  sourcemap: 'external',
  logLevel: 'error',
  tsconfig: path.join(workspace, 'tsconfig.json'),
  entryPoints: {
    index: path.join(workspace, 'src', 'index.tsx'), // Client react app
    style: path.join(workspace, 'src', 'style.css')  // Stylesheet
  },
  outdir: path.join(workspace, 'dist', 'static'),    // Served as /static by express
};

scripts/dev.js: 이 스크립트는 클라이언트와 서버 앱을 모두 번들로 묶고 감시 모드에서 기본 서버 스크립트를 실행합니다.

react-app/             # This will be our workspace directory.
  - public/            
  - scripts/           
    - build.js         # Bundle our server and client scripts.
    - config.js        # esbuild config to bundle.
    - dev.js           # Bundle on watch mode and run server.
  - src/
    - App/             # Our components will be here.
      - App.tsx        # The main application with browser routing.
      - Home.tsx.      # Our default page component.
      - NotFound.tsx   # Fallback page for unmatched routes.
    - index.tsx        # Hydrate our pre-rendered client app.
    - main.tsx         # Server app with SSR components.
    - style.css        # Initial stylesheet.   
  package.json
  tsconfig.json

이 스크립트를 사용하면 작업 공간의 package.json에 구성된 대로 npm run dev를 실행할 수 있습니다.

scripts/build.js: dev와 유사하지만 축소만 활성화하면 됩니다.

{
  "name": "react-app",
  "type": "module",
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/node": "^22.10.2",
    "@types/react": "^19.0.2",
    "@types/react-dom": "^19.0.2",
    "esbuild": "^0.24.2",
    "typescript": "^5.7.2"
  },
  "dependencies": {
    "express": "^4.21.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "react-router-dom": "^7.1.0"
  },
  "scripts": {
    "build": "node scripts/build",
    "dev": "node scripts/dev",
    "start": "node dist/main.js"
  }
}

이 스크립트는 npm run build를 실행하고 npm start를 사용하여 앱을 실행하여 프로덕션용 dist 번들을 생성합니다.

이제 노드와 클라이언트 앱을 모두 번들로 묶도록 esbuild를 구성했으므로 Express 서버 생성과 React SSR 구현을 시작해 보겠습니다.

Express 앱 및 라우팅

이것은 정적 파일을 제공하고, 서버 경로를 처리하고, 반응 라우터-dom을 사용하여 경로를 지정하기 위해 Express 정적 및 미들웨어 접근 방식을 사용하는 간단한 애플리케이션입니다.

src/main.tsx: 서버를 초기화하고, Express로 경로를 처리하고, React SSR을 구현하는 기본 Node.js 애플리케이션입니다.

{
  "compilerOptions": {
    "esModuleInterop": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "lib": ["DOM", "DOM.Iterable", "ES2022"],
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "baseUrl": ".",
    "paths": {
      "src": [
        "./src/"
      ]
    }
  },
  "include": [
    "src"
  ],
  "exclude": [
    "node_modules"
  ]
}

리액트 앱

React 앱은 React-Router-dom을 사용하여 경로를 처리합니다. 우리 앱은 수분 공급을 테스트하기 위한 홈 페이지와 NotFound 페이지로 구성됩니다. 홈 페이지에 카운터 버튼을 추가하고 React 19를 활용할 것입니다. 메타 태그 제목과 설명을 업데이트하세요.

src/App/Home.tsx: 매우 최소한의 FunctionComponent.

import path from 'node:path';
// Working dir
const workspace = process.cwd();
// Server bundle configuration
export const serverConfig = {
  bundle: true,
  platform: 'node', 
  format: 'esm',        // Support esm packages
  packages: 'external', // Omit node packages from our node bundle
  logLevel: 'error',
  sourcemap: 'external',
  entryPoints: {
    main: path.join(workspace, 'src', 'main.tsx') // Express app
  },
  tsconfig: path.join(workspace, 'tsconfig.json'),
  outdir: path.join(workspace, 'dist')
};

// Client bundle configuration
export const clientConfig = {
  bundle: true,
  platform: 'browser',
  format: 'esm',
  sourcemap: 'external',
  logLevel: 'error',
  tsconfig: path.join(workspace, 'tsconfig.json'),
  entryPoints: {
    index: path.join(workspace, 'src', 'index.tsx'), // Client react app
    style: path.join(workspace, 'src', 'style.css')  // Stylesheet
  },
  outdir: path.join(workspace, 'dist', 'static'),    // Served as /static by express
};

src/App/NotFound.tsx: 페이지를 찾을 수 없는 경우 기본 FunctionComponent.

import { spawn } from 'node:child_process';
import path from 'node:path';
import { context } from 'esbuild';
import { serverConfig, clientConfig } from './config.js';
// Working dir
const workspace = process.cwd();
// Dev process
async function dev() {
  // Build server in watch mode
  const serverContext = await context(serverConfig);
  serverContext.watch();
  // Build client in watch mode
  const clientContext = await context(clientConfig);
  clientContext.watch();
  // Run server
  const childProcess = spawn('node', [
    '--watch',
    path.join(workspace, 'dist', 'main.js')
  ], {
    stdio: 'inherit'
  });
  // Kill child process on program interruption
  process.on('SIGINT', () => {
    if (childProcess) {
      childProcess.kill();
    }
    process.exit(0);
  });
}
// Start the dev process
dev();

src/App/App.tsx: React-router-dom을 사용하여 앱 설정

import { build } from 'esbuild';
import { clientConfig, serverConfig } from './config.js';
// build process
async function bundle() {
  // Build server
  await build({
    ...serverConfig,
    minify: true
  });
  // Build client
  await build({
    ...clientConfig,
    minify: true
  });
}
// Start the build process
bundle();

달리다

마지막으로 esbuild 스크립트를 구성하고 Express 서버를 설정하고 React SSR을 구현했습니다. 서버를 실행할 수 있습니다:

import path from 'node:path';
import express, { type Request, type Response } from 'express';
import { renderToPipeableStream } from 'react-dom/server';
import { StaticRouter } from 'react-router';
import { App } from './App/App';

const app = express(); // Create Express App
const port = 3000; // Port to listen
const workspace = process.cwd(); // workspace
// Serve static files like js bundles and css files
app.use('/static', express.static(path.join(workspace, 'dist', 'static')));
// Server files from the /public folder
app.use(express.static(path.join(workspace, 'public')));
// Fallback to render the SSR react app
app.use((request: Request, response: Response) => {
  // React SSR rendering as a stream
  const { pipe } = renderToPipeableStream(
    
      
        <meta charset="UTF-8">
        <link rel="stylesheet" href="%7B%60/static/style.css%60%7D">
      
      
        <base href="/">
        <div>


<p>src/index.tsx: On the client side to activate our components and make them interactive we need to "hydrate".<br>
</p>
<pre class="brush:php;toolbar:false">import { hydrateRoot } from 'react-dom/client';
import { BrowserRouter } from 'react-router';
import { App } from './App/App';
// Hydrate pre-renderer #app element
hydrateRoot(
  document.getElementById('app') as HTMLElement,
  <browserrouter>
    <app></app>
  </browserrouter>
);

포트 3000에서 수신 대기 중인 [app] 메시지가 표시됩니다.
로 이동하세요. http://localhost:3000에서 확인해 보세요.

SSR 및 SEO 메타 태그 테스트:

내 저장소 willyelm/react-app에서도 이 튜토리얼의 소스 코드를 찾을 수 있습니다

윌렘 / 반응 앱

SSR 및 esbuild를 사용한 간단한 반응 앱 설정

이 프로젝트는 React@19, React-router-dom@7 등의 최신 기능을 활용하여 SSR을 구성합니다.

종속성

• react: 구성 요소 기반의 대화형 UI 라이브러리.
• react-dom: React 기능으로 SSR 콘텐츠에 수분을 공급합니다.
• react-router-dom: React로 경로를 처리합니다.
• express: 정적 및 REST API를 위한 Node.js 단순 서버.
• esbuild: Transile TypeScript 및 JS, CSS, SVG 및 기타 파일을 번들로 제공합니다.
• typescript: 소스 코드에 타이핑 추가

프로젝트 구조

react-app/             # This will be our workspace directory.
  - public/            
  - scripts/           
    - build.js         # Bundle our server and client scripts.
    - config.js        # esbuild config to bundle.
    - dev.js           # Bundle on watch mode and run server.
  - src/
    - App/             # Our components will be here.
      - App.tsx        # The main application with browser routing.
      - Home.tsx.      # Our default page component.
      - NotFound.tsx   # Fallback page for unmatched routes.
    - index.tsx        # Hydrate our pre-rendered client app.
    - main.tsx         # Server app with SSR components.
    - style.css        # Initial stylesheet.   
  package.json
  tsconfig.json

…

GitHub에서 보기

다음 단계

이 가이드에서는 최소한의 유연한 설정에 중점을 두고 esbuild 및 Express를 사용하여 SSR로 React 앱을 구축했습니다. React 19, React Router DOM 7 및 esbuild와 같은 최신 도구를 사용하여 더 큰 프레임워크의 오버헤드를 피하면서 빠르고 효율적인 워크플로를 달성했습니다.

이 구현을 개선하여 다음을 포함할 수 있습니다.

• TailwindCSS: 스타일 지정을 위해 tailwindcss를 지원하도록 PostCSS 및 esbuild를 구성합니다.
• Jest: Jest 및 @testing-library를 사용하여 단위 테스트를 추가합니다.
• 극작가: 극작가와 함께 엔드투엔드 테스트를 구성합니다.
• SSG: SSG(정적 사이트 생성)를 구현하여 성능 및 서버 로딩을 개선합니다.
• HMR: 개발 모드에서 esbuild로 HMR(Hot Module replacement)을 지원하여 효율성을 높입니다.

읽어주셔서 감사하고 즐거운 코딩하세요.

참고자료

• 리액트19
• 리액트 라우터 DOM
• 리액트 SSR
• Express.js
• 타입스크립트
• 에스빌드