Справочник API

createRenderer

Создаёт экземпляр Renderer с (опциональными) настройками.

const { createRenderer } = require('vue-server-renderer')
const renderer = createRenderer({ /* настройки */ })

createBundleRenderer

Создаёт экземпляр BundleRenderer с сборкой сервера и (опциональными) настройками.

const { createBundleRenderer } = require('vue-server-renderer')
const renderer = createBundleRenderer(serverBundle, { /* настройки */ })

Аргумент serverBundle может быть одним из следующих:

  • Абсолютный путь к созданному файлу сборки (.js или .json). Должен начинаться с /, чтобы трактоваться как путь к файлу.

  • Объект сборки, сгенерированный Webpack + vue-server-renderer/server-plugin.

  • Строка с кодом JavaScript (не рекомендуется).

Подробнее в разделах Представляем Bundle Renderer и Конфигурация сборки.

Класс: Renderer

renderer.renderToString

Сигнатура:

renderer.renderToString(vm, context?, callback?): ?Promise<string>

Рендерит экземпляр Vue в строку. Объект контекста опционален. Коллбэк является обычным для Node.js коллбэком, где первый аргумент является ошибкой, а второй аргумент — отрендеренной строкой.

С версии 2.5.0+ коллбэк является опциональным. Когда коллбэк не указан, метод возвращает Promise, который разрешается отрендеренным HTML.

renderer.renderToStream

Сигнатура:

renderer.renderToStream(vm[, context]): stream.Readable

Рендерит экземпляр Vue в Node.js readable stream. Объект контекста опционален. Подробнее в разделе Стриминг.

Класс: BundleRenderer

bundleRenderer.renderToString

Сигнатура:

bundleRenderer.renderToString([context, callback]): ?Promise<string>

Рендерит сборку в строку. Объект контекста опционален. Коллбэк является обычным для Node.js коллбэком, где первый аргумент является ошибкой, а второй аргумент — отрендеренной строкой.

С версии 2.5.0+ коллбэк является опциональным. Когда коллбэк не указан, метод возвращает Promise, который разрешается отрендеренным HTML.

bundleRenderer.renderToStream

Сигнатура:

bundleRenderer.renderToStream([context]): stream.Readable

Рендерит сборку в Node.js readable stream. Объект контекста опционален. Подробнее в разделе Стриминг.

Опции рендерера

template

Предоставляет шаблон для всей HTML-страницы. Шаблон должен содержать комментарий <!--vue-ssr-outlet-->, который определяет место подстановки отрендеренного контента приложения.

Шаблон также поддерживает базовые интерполяции с использованием контекста рендера:

  • Используйте двойные фигурные скобки для интерполяции экранированного HTML;
  • Используйте тройные фигурные скобки для интерполяции сырого HTML.

Шаблон автоматически внедряет соответствующий контент, когда определённые свойства найдены в контексте рендера:

  • context.head: (string) любая разметка для head, которая должна быть вставлена в заголовочный тег страницы.

  • context.styles: (string) любой встроенный CSS, который должен быть вставлен в заголовочный тег страницы. Обратите внимание, что это свойство будет автоматически заполнено при использовании vue-loader + vue-style-loader для CSS компонента.

  • context.state: (Object) начальное состояние хранилища Vuex, которое должно быть внедрено в страницу как window.__INITIAL_STATE__. Внедряемый JSON автоматически обрабатывается с помощью serialize-javascript для предотвращения XSS-уязвимостей.

    С версии 2.5.0+, встраиваемый скрипт также автоматически удаляется в режиме production.

Кроме того, когда предоставлен clientManifest, шаблон автоматически внедряет следующее:

  • JavaScript и CSS ресурсы для клиентской части, необходимые для рендеринга (с асинхронными фрагментами добавляемыми автоматически);
  • Оптимальные ресурсы <link rel="preload/prefetch"> для отображаемой страницы.

Вы можете отключить все автоматические внедрения передав inject: false в рендерер.

См. также:

clientManifest

Предоставляет объект манифеста клиентской сборки, сгенерированный vue-server-renderer/client-plugin. Клиентский манифест предоставляет для рендерера сборки необходимую информацию для автоматического внедрения ресурсов в шаблон HTML. Подробнее в разделе Генерация clientManifest.

inject

Контролирует, выполнять ли автоматические внедрения при использовании template. По умолчанию true.

См. также: Внедрение ресурсов вручную.

shouldPreload

Функция, определяющая какие файлы должны иметь <link rel="preload"> в генерируемых ресурсах.

По умолчанию, только JavaScript и CSS файлы будут предзагружаться, так как они абсолютно необходимы для загрузки приложения.

Для других типов ресурсов, таких как изображения или шрифты, предзагрузка может привести к ненужному увеличению объёмов передаваемой информации и даже к ухудшению производительности, поэтому список файлов, которые нужно предзагружать, зависит от ситуации. Вы можете точно контролировать, что требует предзагрузки, используя опцию shouldPreload:

const renderer = createBundleRenderer(bundle, {
  template,
  clientManifest,
  shouldPreload: (file, type) => {
    // тип определяется на основе расширения файла.
    // https://fetch.spec.whatwg.org/#concept-request-destination
    if (type === 'script' || type === 'style') {
      return true
    }
    if (type === 'font') {
      // предзагружать только woff2 шрифты
      return /\.woff2$/.test(file)
    }
    if (type === 'image') {
      // предзагружать только важные изображения
      return file === 'hero.jpg'
    }
  }
})

shouldPrefetch

  • Добавлено в версии 2.5.0+

Функция для управления файлами, которые должны содержаться в генерируемых <link rel="prefetch">.

По умолчанию все ресурсы в асинхронных частях будут предварительно загружены, так как это директива с низким приоритетом; однако вы можете настроить что требуется предзагружать для лучшего контроля над использованием канала загрузки. Этот параметр ожидает такую же сигнатуру функции, как shouldPreload.

runInNewContext

  • Используется только в createBundleRenderer
  • Возможные значения: boolean | 'once' ('once' поддерживается только с версии 2.3.1+)

По умолчанию, рендерер сборки будет создавать новый контекст V8 для каждого рендеринга и повторно исполнять всю сборку. Это имеет некоторые преимущества — например, код приложения изолирован от процесса сервера и не нужно беспокоиться о проблеме «синглтона с состоянием», которая упоминалась ранее в руководстве. Однако этот режим требует значительных затрат производительности, поскольку повторное выполнение сборки обходится дорого, особенно когда приложение становится большим.

По умолчанию эта опция имеет значение true для обеспечения обратной совместимости, но рекомендуется использовать runInNewContext: false или runInNewContext: 'once' всегда, когда это возможно.

В версии 2.3.0 у этой опции есть ошибка, когда при runInNewContext: false сборка всё ещё исполнялась в отдельном глобальном контексте. Информация далее предполагает использование версии 2.3.1+.

С опцией runInNewContext: false, код сборки будет выполняться в том же контексте global, что и серверный процесс, поэтому нужно быть осторожным с кодом, который изменяет global в вашем приложении.

С опцией runInNewContext: 'once' (добавлено в версии 2.3.1+), сборка выполняется в отдельном контексте global, но только один раз при запуске. Это обеспечивает лучшую изоляцию кода приложения поскольку предотвращает случайно загрязнение объекта global серверного процесса. Предостережения заключаются в следующем:

  1. Зависимости, которые изменяют global (например, полифиллы) не должны быть объявлены внешними зависимостями в этом режиме;
  2. Значения, возвращаемые при выполнении сборки будут использовать разные глобальные конструкторы, например, ошибка внутри сборки не будет экземпляром Error в серверном процессе.

См. также: Структура исходного кода

basedir

  • Используется только в createBundleRenderer

Указание пути базового каталога для серверной сборки для разрешения зависимостей из node_modules в нём. Это необходимо только в том случае, если сгенерированный файл сборки располагается в другом месте, в отличии от используемых NPM-зависимостей, или когда ваш vue-server-renderer подключен NPM-ссылкой в вашем текущем проекте.

cache

Реализация кэширования на уровне компонентов. Объект кэша должен реализовать следующий интерфейс (соответствуя нотациям Flow):

type RenderCache = {
  get: (key: string, cb?: Function) => string | void;
  set: (key: string, val: string) => void;
  has?: (key: string, cb?: Function) => boolean | void;
};

Для обычного использования достаточно передать lru-cache:

const LRU = require('lru-cache')

const renderer = createRenderer({
  cache: LRU({
    max: 10000
  })
})

Обратите внимание, что объект кэша по крайне мере должен реализовывать get и set. Кроме того, get и has опционально могут быть асинхронными, если они принимают второй аргумент как коллбэк. Это позволяет кэшу использовать асинхронные API, например для Redis:

const renderer = createRenderer({
  cache: {
    get: (key, cb) => {
      redisClient.get(key, (err, res) => {
        // обработка ошибок, если таковые будут
        cb(res)
      })
    },
    set: (key, val) => {
      redisClient.set(key, val)
    }
  }
})

directives

Позволяет предоставить серверную реализацию для ваших пользовательских директив:

const renderer = createRenderer({
  directives: {
    example (vnode, directiveMeta) {
      // преобразуем vnode на основе метаданных привязанных к директиве
    }
  }
})

Например, можете посмотреть серверную реализацию для директивы v-show.

Плагины webpack

Webpack плагины предоставляются как отдельные файлы, которые должны быть подключены напрямую:

const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')

По умолчанию генерируются файлы:

  • vue-ssr-server-bundle.json для серверной сборки;
  • vue-ssr-client-manifest.json для клиентской сборки.

Имена файлов могут быть изменены при создании экземпляров плагина:

const plugin = new VueSSRServerPlugin({
  filename: 'my-server-bundle.json'
})

Подробнее в разделе Конфигурация сборки.