API リファレンス
createRenderer([options])
任意の引数 options を用いて Renderer
インスタンスを生成します。
const { createRenderer } = require('vue-server-renderer')
const renderer = createRenderer({ ... })
createBundleRenderer(bundle[, options])
サーババンドルと任意の引数 options を用いて BundleRenderer
インスタンスを生成します。
const { createBundleRenderer } = require('vue-server-renderer')
const renderer = createBundleRenderer(serverBundle, { ... })
引数 serverBundle
には次のいずれか1つを指定できます:
- 生成されたバンドルファイル (
.js
または.json
)への絶対パス。ファイルパスとして扱われるために/
で開始されなければなりません。 - webpack と
vue-server-renderer/server-plugin
によって生成されたバンドルオブジェクト。 - JavaScript コードの文字列 (非推奨)。
より詳しい情報は、 サーババンドルの紹介 と ビルド設定 の項目を参照してください。
クラス: Renderer
renderer.renderToString(vm[, context], callback)
Vue インスタンスを文字列として描画します。context オブジェクトの指定は、任意です。callback は、第1引数にエラー内容、 第2引数に描画された文字列を受け取る、典型的な Node.js のコーディングスタイルである関数を指定します。
renderer.renderToStream(vm[, context])
Vue インスタンスを Node.js のストリームへ描画します。context オブジェクトの指定は任意です。より詳しい情報は、ストリーミング の項目を参照してください。
クラス: BundleRenderer
bundleRenderer.renderToString([context, ]callback)
サーババンドルを文字列として描画します。context オブジェクトの指定は、任意です。callback は、第1引数にエラー内容、 第2引数に描画された文字列を受け取る、典型的な Node.js のコーディングスタイルである関数を指定します。
bundleRenderer.renderToStream([context])
サーババンドルを Node.js のストリームへ描画します。context オブジェクトの指定は任意です。より詳しい情報は、ストリーミング の項目を参照してください。
レンダラオプション
template
ページ全体の 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 へサニタイズされます。
加えて、clientManifest
も渡された場合、テンプレートは自動で以下を挿入します。
- (自動で受信される非同期のデータを含んだ)描画対象が必要とするクライアントサイドの JavaScript と CSS アセット
- 描画済みのページに対する最適な
<link rel="preload/prefetch">
リソースヒント
レンダラに inject: false
も渡すことで、すべての自動挿入を無効にすることができます。
参照:
- ページテンプレートの使用
- 手動によるアセットインジェクション
clientManifest
- 2.3.0以上
vue-server-renderer/server-plugin
によって生成されたクライアントビルドマニフェストオブジェクトを提供します。クライアントマニフェストは、HTML テンプレートへの自動アセット挿入に適した情報とともに、バンドルレンダラを提供します。より詳しい情報は クライアントマニフェストの生成 の項目を参照してください。
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) => {
// 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 以降でのみサポートされる)
デフォルトでは、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
- 2.2.0以上
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 のような流れになります:
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
のサーバサイド実装はこちら です。
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'
})
より詳しい情報は、 ビルド設定 の項目を参照してください。