API リファレンス
createRenderer
任意の引数 options を用いて Renderer
インスタンスを生成します。
const { createRenderer } = require('vue-server-renderer')
const renderer = createRenderer({ /* options */ })
createBundleRenderer
サーババンドルと任意の引数 options を用いて BundleRenderer
インスタンスを生成します。
const { createBundleRenderer } = require('vue-server-renderer')
const renderer = createBundleRenderer(serverBundle, { /* options */ })
引数 serverBundle
には次のいずれか1つを指定できます:
生成されたバンドルファイル (
.js
または.json
)への絶対パス。ファイルパスとして扱われるために/
で開始されなければなりません。webpack と
vue-server-renderer/server-plugin
によって生成されたバンドルオブジェクト。JavaScript コードの文字列 (非推奨)。
より詳しい情報は、 サーババンドルの紹介 と ビルド設定 の項目を参照してください。
クラス: Renderer
renderer.renderToString
シグネチャ:
renderer.renderToString(vm[, context, callback]): ?Promise<string>
Vue インスタンスを文字列として描画します。context オブジェクトの指定は、任意です。callback は、第1引数にエラー内容、 第2引数に描画された文字列を受け取る、典型的な Node.js のコーディングスタイルである関数を指定します。
2.5.0 以降においては、コールバックはオプションです。コールバックなしで渡されるとき、HTML に描画されるのを解決するプロミスを返します。
renderer.renderToStream
シグネチャ:
renderer.renderToStream(vm[, context]): stream.Readable
Vue インスタンスを Node.js の読み取り可能なストリーム (opens new window) に描画します。より詳細については、ストリーミング を参照してください。
クラス: BundleRenderer
bundleRenderer.renderToString
シグネチャ:
bundleRenderer.renderToString([context, callback]): ?Promise<string>
サーババンドルを文字列として描画します。context オブジェクトの指定は、任意です。callback は、第1引数にエラー内容、 第2引数に描画された文字列を受け取る、典型的な Node.js のコーディングスタイルである関数を指定します。
2.5.0 以降においては、コールバックは任意です。コールバックなしで渡されたとき、そのメソッドは描画された HTML に解決するプロミスを返します。
bundleRenderer.renderToStream
シグネチャ:
bundleRenderer.renderToStream([context]): stream.Readable
バンドルを Node.js の読み取り可能なストリーム (opens new window)に描画します。コンテキストオブジェクトはオプションです。より詳細は ストリーミングを参照してください。
レンダラオプション
template
- 型:
string
string | (() => string | Promise<string>)
(2.6 から)
文字列テンプレートを使用している場合:
ページ全体の HTML を表すテンプレートを設定します。描画されたアプリケーションの内容を指し示すプレースホルダの代わりになるコメント文 <!--vue-ssr-outlet-->
をテンプレートには含むべきです。
テンプレートは、次の構文を使用した簡単な補間もサポートします。
- エスケープされたHTMLを補間する Mustache 構文(二重中括弧)の使用
- エスケープしない生のHTMLを補間する Mustache 構文(三重中括弧)の使用
次の構文を見つけた時、テンプレートは自動で適切な内容を挿入します。
context.head
: (string) ページ内の head に挿入されるべき任意のマークアップを文字列で指定します。context.styles
: (string) ページ内の head に挿入されるべき任意のインライン CSS を文字列で指定します。もし CSS コンポーネントのためにvue-loader
+vue-style-loader
を使用する場合、このプロパティは自動で追加されることに注意してください。context.state
: (Object)window.__INITIAL_STATE__
としてページ内にインライン展開されるべき Vuex のストアの初期状態を指定します。このインライン JSON は自動でクロスサイトスプリクティングを防ぐ シリアライズされた javascript (opens new window) へサニタイズされます。2.5.0 以降においては、埋め込みスクリプトはプロダクションモードで自動的に削除されます。
2.6.0 以降では、
context.nonce
が存在すれば、それは、埋め込みスクリプトにnonce
属性として追加されます。これにより、インラインスクリプトを nonce を必要とする CSP に準拠することができます。
加えて、clientManifest
も渡された場合、テンプレートは自動で以下を挿入します。
- (自動で受信される非同期のデータを含んだ)描画対象が必要とするクライアントサイドの JavaScript と CSS アセット
- 描画済みのページに対する最適な
<link rel="preload/prefetch">
リソースヒント
レンダラに inject: false
も渡すことで、すべての自動挿入を無効にすることができます。
関数テンプレートを使用している場合:
WARNING
関数テンプレートは renderer.renderToString
を使用するとき、2.6 以降でのみサポートされます。renderer.renderToStream
はまだサポートされていません。
template
オプションは、描画された HTML 、もしくは描画された HTML を解決する Promise を返す関数を指定できます。これにより、テンプレート文字列、そしてテンプレート描画プロセスにあり得る非同期な操作を利用できます。
関数は 2 つの引数を受け取ります:
- アプリケーションコンポーネントの描画結果の文字列
- 描画コンテキストオブジェクト
例:
const renderer = createRenderer({
template: (result, context) => {
return `<html>
<head>${context.head}</head>
<body>${result}</body>
<html>`
}
})
カスタムテンプレート関数を使用するとき、自動的に注入されるものが何もないことに注意してください。最終的な HTML に含まれるものを完全に制御できますが、全てあなた自身で含める必要があります (例えば、バンドルレンダラを使用する場合のアセットのリンク)。
参照:
clientManifest
vue-server-renderer/server-plugin
によって生成されたクライアントビルドマニフェストオブジェクトを提供します。クライアントマニフェストは、HTML テンプレートへの自動アセット挿入に適した情報とともに、バンドルレンダラを提供します。より詳しい情報は クライアントマニフェストの生成 の項目を参照してください。
inject
template
使用時に、自動挿入を行うかどうかを制御します。デフォルトは true
です。
shouldPreload
どのファイルが <link rel="preload">
生成済みのリソースヒント持つべきか制御するための関数を指定します。
デフォルトでは、JavaScript と CSS ファイルのみがプリロードされます。これらはアプリケーション起動時に必須なためです。
画像やフォントのようなその他のアセット種別を指定した際、 多すぎるプリロードは処理能力を無駄にし、またパフォーマンスさえも損なうかもしれません。そのため、 プリロードすべきものはアプリケーションの実装依存になるでしょう。 次のように shouldPreload
オプションを使用することで、プリロードすべきものを正確に制御できます。
const renderer = createBundleRenderer(bundle, {
template,
clientManifest,
shouldPreload: (file, type) => {
// 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 以降でのみサポートされる)
デフォルトでは、BundleRenderer の描画ごとに未使用の 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 依存関係とは異なる場所に置かれた生成済みバンドルファイル、または、あなたの現在のプロジェクト内へ npm link された vue-server-renderer
のみが必要です。
cache
コンポーネントキャッシュ の実装を提供します。 キャッシュオブジェクトは以下のインタフェースで実装しなければいけません(以下のような記法を用いる):
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
は、もし第 2 引数に callback が指定された場合、必要に応じてこれを非同期処理にできます。これは、非同期 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 文字を適切にエスケープする関数を使用することは重要です。デフォルトシリアライザは、{ isJSON: true }
がセットされた serialize-javascript (opens new window) です。
サーバのみのコンポーネントオプション
serverCacheKey
型:
(props) => any
受信プロパティ (incoming props) に基づいたコンポーネントのキャッシュキーを返します。
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'
})
より詳しい情報は、 ビルド設定 の項目を参照してください。