Справочник 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 (opens new window). Объект контекста опционален. Подробнее в разделе Стриминг.

Класс: BundleRenderer

bundleRenderer.renderToString

Сигнатура:

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

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

bundleRenderer.renderToStream

Сигнатура:

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

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

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

template

Тип:
- string
- string | (() => string | Promise<string>) (с версии 2.6)

При использовании строкового шаблона:

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

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

Используйте двойные фигурные скобки для интерполяции экранированного 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 (opens new window) для предотвращения XSS-уязвимостей.

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

С версии 2.6.0+, если присутствует context.nonce, он будет добавлен как атрибут nonce во встраиваемый скрипт. Это позволит встраиваемому скрипту соответствовать CSP, который требует nonce.

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

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

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

При использовании функции шаблона:

ВНИМАНИЕ

Шаблоны в виде функции поддерживаются только с версии 2.6+ и при использовании renderer.renderToString. Это НЕ ПОДДЕРЖИВАЕТСЯ в renderer.renderToStream.

Опция template также может быть функцией, которая возвращает отрендеренный HTML или Promise, который разрешится отрендеренным HTML. Это позволит использовать собственные строковые шаблоны JavaScript и потенциальные асинхронные операции в процессе рендеринга шаблона.

Функция принимает два аргумента:

Результат рендеринга компонента приложения в виде строки;
Объект контекста рендеринга.

Пример:

const renderer = createRenderer({
  template: (result, context) => {
    return `<html>
      <head>${context.head}</head>
      <body>${result}</body>
    <html>`
  }
})

Обратите внимание, что при использовании собственной функции для шаблона ничего автоматически не будет добавляться — вы полностью контролируете то, что будет включаться в HTML, но также нести ответственность за включение всего необходимого (например, ссылки на ресурсы, если вы используете bundle renderer).

См. также:

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 серверного процесса. Предостережения заключаются в следующем:

Зависимости, которые изменяют global (например, полифилы) не должны быть объявлены внешними зависимостями в этом режиме;
Значения, возвращаемые при выполнении сборки будут использовать разные глобальные конструкторы, например, ошибка внутри сборки не будет экземпляром 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 (opens new window):

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 (opens new window).

serializer

Добавлено в версии 2.6

Пользовательская функция сериализатора для context.state. Поскольку сериализованное состояние будет частью вашего итогового HTML, важно использовать функцию, которая должным образом экранирует символы HTML по соображениям безопасности. Сериализатор по умолчанию — serialize-javascript (opens new window) с опцией { isJSON: true }.

Опции компонента только для сервера

serverCacheKey

Тип: (props) => any

Возвращает ключ кэша для компонента на основе входных параметров. НЕ ИМЕЕТ доступа к this.

Начиная с версии 2.6, вы можете явно отказываться от кэширования, возвращая значение false.

Подробнее в Кэшировании на уровне компонентов.

serverPrefetch

Тип: () => Promise<any>

Загрузка асинхронных данных во время рендеринга на стороне сервера. Он должен сохранить полученные данные в глобальном хранилище или вернуть Promise. Рендерер сервера будет дожидаться разрешения Promise в этом хуке. Этот хук имеет доступ к экземпляру компонента через this.

Подробнее в Предзагрузке данных и состояния.

Плагины 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'
})

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

# Справочник API

# createRenderer

# createBundleRenderer

# Класс: Renderer

# renderer.renderToString

# renderer.renderToStream

# Класс: BundleRenderer

# bundleRenderer.renderToString

# bundleRenderer.renderToStream

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

# template

# clientManifest

# inject

# shouldPreload

# shouldPrefetch

# runInNewContext

# basedir

# cache

# directives

# serializer

# Опции компонента только для сервера

# serverCacheKey

# serverPrefetch

# Плагины webpack

Справочник API

createRenderer

createBundleRenderer

Класс: Renderer

renderer.renderToString

renderer.renderToStream

Класс: BundleRenderer

bundleRenderer.renderToString

bundleRenderer.renderToStream

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

template

clientManifest

inject

shouldPreload

shouldPrefetch

runInNewContext

basedir

cache

directives

serializer

Опции компонента только для сервера

serverCacheKey

serverPrefetch

Плагины webpack