Nuxt는 어떻게 동작하나요?

이 가이드는 Nuxt 내부 구조를 더 잘 이해하여 Nuxt 위에 새로운 솔루션과 모듈 통합을 개발할 수 있도록 도와줍니다.

Nuxt 인터페이스

nuxt dev로 개발 모드에서 Nuxt를 시작하거나 nuxt build로 프로덕션 애플리케이션을 빌드할 때, nuxt라고 불리는 공통 컨텍스트가 내부적으로 생성됩니다. 이 컨텍스트는 nuxt.config 파일과 병합된 정규화된 옵션, 일부 내부 상태, 그리고 unjs/hookable로 구동되는 강력한 훅 시스템을 포함하고 있어 서로 다른 컴포넌트들이 서로 통신할 수 있게 해줍니다. 이를 빌더 코어(Builder Core) 로 생각할 수 있습니다.

이 컨텍스트는 Nuxt Kit 컴포저블에서 사용할 수 있도록 전역으로 제공됩니다. 따라서 프로세스당 하나의 Nuxt 인스턴스만 실행할 수 있습니다.

Nuxt 인터페이스를 확장하고 빌드 프로세스의 다양한 단계에 훅을 연결하기 위해 Nuxt 모듈을 사용할 수 있습니다.

자세한 내용은 소스 코드를 확인하세요.

NuxtApp 인터페이스

브라우저나 서버에서 페이지를 렌더링할 때, nuxtApp이라고 불리는 공유 컨텍스트가 생성됩니다. 이 컨텍스트는 vue 인스턴스, 런타임 훅, ssrContext 및 하이드레이션을 위한 payload와 같은 내부 상태를 유지합니다. 이를 런타임 코어(Runtime Core) 로 생각할 수 있습니다.

이 컨텍스트는 Nuxt 플러그인과 <script setup> 및 vue 컴포저블 내에서 useNuxtApp() 컴포저블을 사용해 접근할 수 있습니다. 브라우저에서는 전역 사용이 가능하지만, 서버에서는 사용자 간 컨텍스트 공유를 피하기 위해 전역 사용이 불가능합니다.

useNuxtApp은 컨텍스트를 현재 사용할 수 없을 때 예외를 발생시키므로, 컴포저블이 항상 nuxtApp을 필요로 하지 않는다면 예외를 던지는 대신 null을 반환하는 tryUseNuxtApp을 대신 사용할 수 있습니다.

nuxtApp 인터페이스를 확장하고 다양한 단계에 훅을 연결하거나 컨텍스트에 접근하기 위해 Nuxt 플러그인을 사용할 수 있습니다.

이 인터페이스에 대한 더 많은 정보는 Nuxt App을 확인하세요.

nuxtApp은 다음과 같은 속성을 가집니다:

interface NuxtApp {
  vueApp // 전역 Vue 애플리케이션: https://vuejs.org/api/application.html#application-api

  versions // Nuxt와 Vue 버전을 포함하는 객체

  // 런타임 NuxtApp 훅을 호출하고 추가할 수 있게 해줍니다
  // https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts#L18
  hooks
  hook
  callHook

  // 서버 사이드에서만 접근 가능
  ssrContext: {
    url
    req
    res
    runtimeConfig
    noSSR
  }

  // 이 객체는 문자열로 변환되어 서버에서 클라이언트로 전달됩니다
  payload: {
    serverRendered: true
    data: {}
    state: {}
  }

  provide: (name: string, value: any) => void
}

자세한 내용은 소스 코드를 확인하세요.

런타임 컨텍스트 vs. 빌드 컨텍스트

Nuxt는 Node.js를 사용해 프로젝트를 빌드하고 번들링하지만, 동시에 런타임 측면도 가지고 있습니다.

두 영역 모두 확장할 수 있지만, 런타임 컨텍스트는 빌드 타임과 분리되어 있습니다. 따라서 런타임 설정 외에는 상태, 코드 또는 컨텍스트를 공유해서는 안 됩니다!

nuxt.config와 Nuxt 모듈은 빌드 컨텍스트를 확장하는 데 사용할 수 있고, Nuxt 플러그인은 런타임을 확장하는 데 사용할 수 있습니다.

프로덕션용 애플리케이션을 빌드할 때, nuxt build는 .output 디렉터리에 독립 실행형 빌드를 생성하며, 이는 nuxt.config와 Nuxt 모듈과는 독립적입니다.