Справочник API

createRenderer([options])

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

const { createRenderer } = require('vue-server-renderer')
const renderer = createRenderer({ ... })

createBundleRenderer(bundle[, options])

Создаёт экземпляр 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(vm[, context], callback)

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

  • renderer.renderToStream(vm[, context])

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

Класс: BundleRenderer

  • bundleRenderer.renderToString([context, ]callback)

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

  • bundleRenderer.renderToStream([context])

    Рендерит сборку в поток (stream) Node.js. Объект контекста опционален. См. также Стриминг для подробностей.

Настройки рендерера

  • 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-уязвимостей.

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

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

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

    См. также:

  • clientManifest

    • 2.3.0+

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

  • inject

    • 2.3.0+

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

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

  • shouldPreload

    • 2.3.0+

    Функция, определяющая какие файлы должны иметь <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'
        }
      }
    })
    
  • runInNewContext

    • 2.3.0+
    • используется только в 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

    • 2.2.0+
    • используется только в 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'
})

См. также Конфигурация сборки для подробной информации.

results matching ""

    No results matching ""