[Nuxt3] Nitro

Nitro란?

Nitro는 Nuxt 3의 서버 엔진으로, 서버 측 로직(API 엔드포인트, 미들웨어, SSR 등)을 효율적으로 관리할 수 있도록 설계되었습니다. 본래 Nuxt를 위해 만들어졌지만, 현재는 UnJS 생태계로 분리되어 다른 프레임워크에서도 독립적으로 사용 가능합니다. h3 HTTP 프레임워크를 기반으로 동작하며, 고성능 및 범용 배포를 염두에 두고 개발되었습니다.

Nitro의 주요 특징

1. API, 미들웨어, SSR 등 서버 영역을 Nuxt 내부에서 간단히 작성·확장할 수 있습니다.
2. 별도 설정 없이도 다양한 클라우드 및 엣지 플랫폼(Vercel, Netlify, Cloudflare Workers, Deno, Bun 등)에 손쉽게 배포 가능합니다.
3. SSR, SSG, ISR 등 여러 렌더링 방식을 혼합해 사용할 수 있으며, Nuxt 3의 routeRules를 통해 세부 조정이 가능합니다.

기본 Nitro 설정 방법

Nitro 관련 설정은 Nuxt의 메인 설정 파일인 nuxt.config.ts 내 nitro 키 아래에서 지정할 수 있습니다.

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server', // 기본 서버 환경 (ex. node-server, vercel 등)
    serveStatic: true,     // 정적 파일을 서빙할지 여부
  }
});

• preset: 배포 대상 환경에 맞춰 빌드 방식을 최적화합니다.
• serveStatic: 정적 파일(public/ 등)을 서버에서 직접 제공할지 여부.

서버 스토리지 설정

Nitro는 크로스 플랫폼 스토리지 레이어를 제공하여, Redis 등 외부 스토리지를 간단히 연동할 수 있습니다. 

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    storage: {
      redis: {
        driver: 'redis',
        port: 6379,
        host: '127.0.0.1',
        username: '', // Redis 6 이상에서 필요
        password: '',
        db: 0,
        tls: {}
      }
    }
  }
});

// server/api/storage-example.ts
export default defineEventHandler(async () => {
  const storage = useStorage('redis');

  // 데이터 저장
  await storage.setItem('key', 'value');

  // 데이터 조회
  const value = await storage.getItem('key');

  return { value };
});

• useStorage('redis'): 설정된 스토리지 드라이버(redis 등)에 접근해 get/set 메서드를 활용.

Nitro 플러그인 작성

Nitro는 서버 시작 시점 혹은 요청 처리 시점에 훅(Hook) 등을 활용해 특정 동작을 수행할 수 있습니다. Nitro 플러그인을 통해 이를 간단히 정의 가능합니다. defineNitroPlugin 함수 안에서 nitroApp.hooks를 이용해 'request', 'response', 'error' 등 다양한 이벤트에 콜백을 등록할 수 있습니다.

// server/plugins/logger.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('요청 URL:', getRequestURL(event));
  });
});

 

 Nitro 서버 미들웨어 설정

요청을 처리하기 전 공통 로직을 실행하고 싶다면, 서버 미들웨어를 사용합니다.

// server/middleware/security.ts
export default defineEventHandler((event) => {
  setHeader(event, 'X-Content-Type-Options', 'nosniff');
});

• /server/middleware 폴더 내 파일은 Nuxt가 자동으로 미들웨어로 인식하여, 요청 전에 실행됩니다.
• 보안 헤더 설정, 인증 검사 등을 여기에 배치할 수 있습니다.

환경 변수와 Nitro

Nitro 런타임 설정은 .env 파일 등에서 설정된 환경 변수로 동적으로 제어 가능합니다. Nuxt 3에서는 nuxt.config.ts의 runtimeConfig를 통해 이 값을 가져올 수 있으며, 서버 측 코드에서 useRuntimeConfig()로 접근 가능합니다.

NUXT_SECRET_KEY=mysecretkey

// server/api/config-example.ts
export default defineEventHandler(() => {
  const config = useRuntimeConfig();
  return { secret: config.secretKey };
});

 

Nitro로 파일 스트림 제공

Nitro에서는 파일 스트리밍 API를 간단히 구현할 수 있습니다.

// server/api/file.ts
import fs from 'node:fs';
import { sendStream } from 'h3';

export default defineEventHandler((event) => {
  return sendStream(event, fs.createReadStream('/path/to/file'));
});

• sendStream: h3 프레임워크가 제공하는 헬퍼로, Node.js의 ReadStream을 직접 응답으로 전송할 수 있습니다.
• 파일 다운로드, 이미지 변환 등 다양한 파일 처리 로직에 활용할 수 있습니다.