技術資料

Laravelの公式ViteプラグインでWebフォントを設定していると、ビルド時にfontaineが未導入であることを知らせる警告が表示される場合があります。

この警告が出ると、「フォントが使えなくなるのではないか」「ビルドに失敗しているのではないか」と心配になるかもしれません。

先に結論を書くと、fontaineはWebフォントそのものを使うための必須パッケージではありません。主に、Webフォントの読み込み前に表示する代わりのフォントを、Webフォントの見た目に近づけるために使われます。

今回は、Laravelの公式Viteプラグインでfontaine未導入の警告が出た場合に、警告の意味、fontaineを導入する場合、導入しない場合の判断基準を整理します。

この警告はVite全体に共通するものではない

今回の警告は、Vite本体がWebフォントを使うプロジェクトに対して一律に表示しているものではありません。Laravelの公式Viteプラグインにあるフォント機能が、optimizedFallbacksの処理でfontaineを使おうとしたときに表示されます。

そのため、通常のViteプロジェクトでWebフォントを使っていても、同じ警告が必ず出るわけではありません。プロジェクトで使っているフォント用プラグインや設定によって、警告の有無や内容は変わります。

一方で、fontaine自体はLaravel専用のパッケージではありません。単独のViteプラグインとしても利用できるため、Webフォントと代替フォントの大きさの違いによる画面の移動は、Laravel以外のViteプロジェクトでも起こり得ます。Laravel以外の構成では、使用しているプラグインの設定や公式ドキュメントに従って対応してください。

前提

この記事では、Laravelの公式Viteプラグインで、次のようにフォントを設定している構成を対象にします。

• Laravel 13.x
• Vite
• laravel-vite-plugin
• npm
• Google FontsやBunny FontsなどのWebフォント

Laravel、Vite、Node.js、npmのバージョンはプロジェクトによって異なります。記事の手順を試す前に、プロジェクトで使っているバージョンを確認してください。

php artisan --version
node --version
npm --version
npm list vite laravel-vite-plugin fontaine --depth=0

LaravelのViteプラグインは、設定したフォントのファイルをビルド時に取得し、CSSやViteの生成物として扱います。公式ドキュメントでは、Google Fonts、Bunny Fonts、Fontsource、ローカルフォントなどのプロバイダーが案内されています。

実際のプロジェクトで使っているフォント設定を確認しながら読み進めてください。

Webフォントと代わりのフォント

Webフォントとは、Webページの表示時に読み込んで使うフォントです。例えば、ページのCSSで次のように指定しているとします。

body {
    font-family: 'Instrument Sans', system-ui, sans-serif;
}

この場合、ブラウザはまずInstrument Sansを使おうとします。しかし、フォントファイルの読み込みが終わっていなかったり、何らかの理由で利用できなかったりする場合があります。

そのときに代わりに使うフォントが、代替フォントです。上の例では、system-uiやsans-serifが代替フォントの候補になります。

代替フォントを用意しておくと、Webフォントの読み込みが終わるまで文字が表示されない状態を避けやすくなります。一方で、フォントが切り替わると、文字の幅や行の高さが変わることがあります。

フォントメトリクスとは

フォントメトリクスとは、フォントが持っている文字の寸法情報のことです。例えば、次のような情報が含まれます。

• 文字を並べたときの横幅
• 文字の上側に必要な高さ
• 文字の下側に必要な高さ
• 行間の広さ

Webフォントと代替フォントでこれらの値が大きく違うと、フォントの切り替え時に文章の折り返し位置や行の高さが変わることがあります。

例えば、最初は代替フォントで1行に収まっていたボタンの文字が、Webフォントへ切り替わった後に2行になるかもしれません。見出しの高さが変わり、その下にある画像やボタンが下へ移動することもあります。

レイアウトシフトとCLS

ページを表示した後、利用者が操作していないのに、文字やボタンなどの位置が突然動くことがあります。このような予期しない画面上の移動を、レイアウトシフトと呼びます。

CLS（Cumulative Layout Shift）は、ページ内で発生した予期しないレイアウトシフトの大きさを測る指標です。Webフォントと最初の代替フォントの大きさが異なることも、レイアウトシフトの原因になります。

例えば、読み込み後に見出しの幅が変わり、下にあるボタンが移動すると、利用者が押そうとしていた場所と実際のボタンの位置がずれる可能性があります。CLSの詳しい定義や測定方法は、web.devのCLS解説を参照してください。

ただし、レイアウトシフトの原因はフォントだけではありません。画像の高さが未指定だったり、広告や非同期処理で要素が追加されたりする場合もあります。fontaineを導入すれば、すべてのレイアウトシフトが解決するわけではありません。

fontaineの役割

fontaineは、Webフォントの寸法情報をもとに、代替フォントの見た目をWebフォントへ近づけるためのCSSを生成します。

イメージとしては、通常のCSSへ次のような代替フォント用の定義を追加します。

@font-face {
    font-family: 'Instrument Sans fallback';
    src: local('Arial');
    ascent-override: ...;
    descent-override: ...;
    line-gap-override: ...;
}

body {
    font-family: 'Instrument Sans', 'Instrument Sans fallback';
}

実際に生成されるフォント名や数値は、使用するフォントやパッケージのバージョンによって変わります。重要なのは、単にArialを追加するのではなく、Webフォントの寸法に近づけた代替フォントを用意する点です。

fontaineの公式資料では、フォントの定義を読み取り、ascent-override、descent-override、line-gap-overrideなどを使ったCSSを生成すると説明されています。また、処理結果はCSSとして出力され、ブラウザでfontaineのJavaScriptを実行する方式ではありません。

fontaine未導入時に起こること

Laravelの公式Viteプラグインでは、フォント設定のoptimizedFallbacksは既定で有効です。この設定は、fontaineを使って寸法を調整した代替フォントを生成しようとします。

ただし、fontaineは標準でインストールされる必須依存ではありません。未導入の場合、Laravelは調整済みの代替フォント生成を省略し、設定されている通常の代替フォントを使って処理を続けます。

そのため、今回のような警告が出ても、次のすべてが直ちに使えなくなるわけではありません。

• Webフォントのファイル
• 通常の代替フォント
• Viteのビルド
• Laravelアプリケーションの画面

不足するのは、Webフォントの寸法に合わせた代替フォントを生成する処理です。警告は「Webフォントが使えない」という意味ではなく、「指定されている最適化を実行できない」という意味で読み取ると分かりやすいかと思います。

ただし、パッケージのバージョンによって警告文やエラー時の挙動が変わる可能性があります。ビルドの終了コードが失敗を示している場合は、fontaine以外の原因も確認してください。

現在のフォント設定を確認する

まず、プロジェクトのvite.config.jsまたはvite.config.tsを確認します。例えば、LaravelのViteプラグインでBunny FontsのInstrument Sansを指定する場合は、次のような設定になります。

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import { bunny } from 'laravel-vite-plugin/fonts';

export default defineConfig({
    plugins: [
        laravel({
            input: 'resources/js/app.js',
            fonts: [
                bunny('Instrument Sans', {
                    weights: [400, 500, 600],
                    fallbacks: ['system-ui', 'sans-serif'],
                }),
            ],
        }),
    ],
});

既存の設定へ追加するときは、プロジェクトにあるinput、refresh、VueやReactのプラグインなどを削除しないようにしてください。上のコードは設定全体の置き換え例ではなく、フォント設定の位置を確認するための簡略化した例です。

フォント設定がある場合は、現在のプロバイダーがoptimizedFallbacksに対応しているか、フォントの取得方法が何か、fallbacksに何を指定しているかを確認します。

対応方法1：fontaineを導入する

Webフォントの切り替えによる画面の移動をできるだけ抑えたい場合は、fontaineを開発依存として追加します。

npm install --save-dev fontaine

fontaineは、ブラウザが画面を表示している間に読み込むアプリケーション機能ではなく、Viteのビルド時に使うパッケージです。そのため、通常の依存関係ではなくdevDependenciesへ追加します。

インストール後にビルドを実行します。

npm run build

次の項目を確認します。

• fontaine未導入に関する警告が消えたか
• ビルドの終了コードが成功になっているか
• フォントファイルが生成されているか
• 生成されたCSSに代替フォント用の定義が含まれているか
• ブラウザでフォント切り替え時の表示に問題がないか

生成されたCSSの保存場所は、Viteの設定やLaravelの構成によって変わります。public/build/assetsなどの出力先を確認し、フォント名や@font-faceの定義を検索してください。

なお、fontaineを追加しただけでCLSの数値が必ず改善すると決めつけないようにします。ページ全体のレイアウトには画像、広告、非同期通信、JavaScriptによる要素追加なども影響するためです。

対応方法2：optimized fallbackを無効にする

Webフォントを使っていても、画面の利用者が限定されている場合や、代替フォントの微調整を必要としない場合は、最適化を無効にする方法があります。

bunny('Instrument Sans', {
    weights: [400, 500, 600],
    fallbacks: ['system-ui', 'sans-serif'],
    optimizedFallbacks: false,
})

この設定では、fontaineを使った代替フォントの寸法調整を行いません。通常のsystem-uiやsans-serifなどはフォントの候補として残るため、Webフォントが使えなくなる設定ではありません。

依存パッケージを増やさずに警告を出さないようにできますが、Webフォントと代替フォントの幅や高さが異なる場合に、画面が移動する可能性は残ります。

設定を変更した後も、必ずビルドと画面確認を行います。

npm run build

どちらを選ぶか

判断するときは、「警告を消したいか」だけでなく、フォント切り替えによる表示の変化が利用者にとって問題になるかを考えます。

状況	検討しやすい対応
一般ユーザー向けのサービス	fontaineを導入し、表示と性能を確認する
スマートフォンでの表示を重視する	fontaineを導入し、実機でも確認する
社内向け・自分専用の管理画面	表示上の問題がなければ無効化や現状維持も選択肢にする
システムフォントだけを使っている	fontaineを追加しない

一般ユーザー向けサービスでは、利用者の端末や通信環境をこちらで限定できません。文字の切り替えでボタンや見出しが動く場合は、fontaineの導入を検討しやすいでしょう。

一方、開発者だけが使う管理画面で、表示速度や文字の切り替えに困っていないなら、依存パッケージを増やさない判断もできます。必要になったときに導入できるよう、警告の意味だけは把握しておくとよいかと思います。

導入後に画面を確認する

ビルドが成功しただけでは、画面上の効果までは判断できません。ブラウザで次の項目を確認します。

ネットワーク通信を確認する

ブラウザの開発者ツールを開き、NetworkタブでCSSとフォントファイルの通信を確認します。

• フォントファイルが404になっていないか
• CSSから参照されているフォントURLが正しいか
• 想定したウェイトのフォントが読み込まれているか

LaravelのViteプラグインは、設定したフォントをビルド成果物として扱います。開発サーバーでは動くのに本番ビルドで表示できない場合は、生成物の配置先やCSS内のURLも確認してください。

文字の切り替えで画面が動かないか確認する

キャッシュを無効にした状態や、初回アクセスに近い条件でページを表示します。次のような場所を重点的に確認すると、違いに気づきやすくなります。

• 横幅の小さいボタン
• 1行で表示したいナビゲーション
• カードの見出し
• 行数によって高さが変わる一覧

フォントが切り替わる前後で、文字の折り返し、行の高さ、ボタンの幅、周囲の要素の位置を確認します。

CLSを測定する場合の注意

Lighthouseなどの検査ツールを使う場合は、同じ端末、同じブラウザ、同じ回線条件で導入前後を比較します。測定結果は、フォント以外の通信や画面状態にも影響されます。

よくある誤解

fontaineがないとWebフォントを使えない

fontaineが担当するのは、主に代替フォントの調整です。Webフォントそのものを取得してCSSへ組み込む処理とは役割が異なります。

警告を消せば性能問題が解決する

警告が消えることと、画面の表示が速くなることは別です。fontaineは文字の切り替えによる移動を抑えるための仕組みであり、JavaScriptのサイズや画像の読み込み時間を改善するものではありません。

fontaineを導入すれば必ずCLSが下がる

フォント以外の原因で画面が移動している場合、fontaineを追加しても問題は残ります。導入後に効果を説明する場合は、同じ条件で測定した結果を根拠にします。

まとめ

LaravelのViteビルドでfontaine未導入の警告が表示されても、WebフォントやViteのビルドが直ちに使えなくなるわけではありません。通常の代替フォントを使いながら、寸法を調整した代替フォントの生成だけが省略されます。

Webフォントが読み込まれる前に表示される代替フォントは、Webフォントと文字の幅や行の高さが異なる場合があります。その結果、文字の切り替え時にボタンや見出しが動くことがあります。こうした予期しない画面の移動を測る指標がCLSです。

一般ユーザー向けサービスやスマートフォン表示で画面の移動を抑えたい場合は、npm install --save-dev fontaineで導入する方法を検討します。依存を増やしたくない場合や、表示上の問題がない管理画面では、optimizedFallbacks: falseで無効にすることもできます。

重要なのは、警告だけを見て対応を決めることではありません。利用者、画面の要件、フォント切り替え時の表示、ビルド成果物を確認した上で、プロジェクトに合う方法を選びます。

参考資料

• Laravel 13.x Asset Bundling（Vite）
• Laravel Vite Plugin
• fontaine - Automatic font fallback based on font metrics
• Cumulative Layout Shift（CLS） | web.dev
• ViteのJavaScriptチャンクサイズ警告が出たときの判断基準：コード分割・閾値変更・現状維持