Как устроен Nuxt?

Этот гайд помогает глубже понять внутреннее устройство Nuxt, чтобы разрабатывать новые решения и интеграции модулей поверх Nuxt.

Интерфейс Nuxt

Когда вы запускаете Nuxt в режиме разработки командой nuxt dev или собираете production-приложение через nuxt build, создаётся общий контекст, внутри проекта он называется nuxt. В нём хранятся нормализованные опции (слияние с nuxt.config), внутреннее состояние и мощная система хуков на базе unjs/hookable, через которую разные части системы обмениваются сообщениями. Можно думать о нём как о ядре сборки (Builder Core).

Этот контекст глобально доступен для композаблов Nuxt Kit. В одном процессе может работать только один экземпляр Nuxt.

Чтобы расширить интерфейс Nuxt и подключаться к этапам сборки, используйте модули Nuxt.

Подробнее — в исходном коде.

Интерфейс NuxtApp

При рендере страницы в браузере или на сервере создаётся общий контекст nuxtApp. В нём хранятся экземпляр Vue, runtime-хуки и внутреннее состояние вроде ssrContext и payload для гидрации. Это можно считать ядром runtime (Runtime Core).

К нему обращаются через композабл useNuxtApp() в плагинах Nuxt, в <script setup> и во Vue-композаблах. Глобально это допустимо в браузере, но не на сервере — чтобы не смешивать контексты пользователей.

Так как useNuxtApp выбрасывает исключение, если контекст недоступен, а вашему композаблу не всегда нужен nuxtApp, можно использовать tryUseNuxtApp — он вернёт null вместо исключения.

Чтобы расширить nuxtApp и подписаться на этапы или получить доступ к контекстам, используйте плагины Nuxt.

Больше об этом интерфейсе — в разделе Nuxt App.

У nuxtApp есть такие свойства:

interface NuxtApp {
  vueApp // глобальное приложение Vue: https://vuejs.org/api/application.html#application-api

  versions // объект с версиями Nuxt и Vue

  // Вызов и регистрация runtime-хуков 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
}

Подробнее — в исходном коде.

Runtime и сборка

Nuxt собирает и бандлит проект в Node.js, но у него есть и сторона runtime.

Обе области можно расширять, однако runtime изолирован от этапа сборки: между ними не должны разделяться состояние, код или контекст, кроме runtime-конфигурации!

nuxt.config и модули Nuxt расширяют контекст сборки, а плагины Nuxt — runtime.

При production-сборке nuxt build создаёт автономную сборку в каталоге .output, независимую от nuxt.config и модулей Nuxt.