環境 API

実験的機能

環境 API は実験的です。エコシステムが実験し、それらを基盤として構築できるように、メジャーリリース間での API の安定性は引き続き維持されます。ダウンストリームプロジェクトが新機能を実験し、検証する時間を持った後、将来のメジャーリリースでこれらの新しい API を安定化させる予定です（潜在的な破壊的変更を伴う可能性があります）。

リソース

フィードバックディスカッション (新しい API に関するフィードバックを収集しています)
環境 API PR (新しい API が実装され、レビューされた場所)

ぜひフィードバックをお寄せください。

環境の形式化

Vite 6 は、環境の概念を形式化します。Vite 5 までは、2 つの暗黙的な環境 (client と、オプションで ssr) がありました。新しい環境 API により、ユーザーやフレームワークの作者は、本番環境でのアプリの動作方法に合わせて、必要なだけ多くの環境を作成できます。この新しい機能には大規模な内部リファクタリングが必要でしたが、後方互換性には多くの労力が費やされました。Vite 6 の最初の目標は、可能な限りスムーズにエコシステムを新しいメジャーバージョンに移行させ、十分なユーザーが移行し、フレームワークとプラグインの作者が新しい設計を検証するまで、これらの新しい実験的な API の採用を遅らせることです。

ビルドと開発のギャップを埋める

シンプルな SPA/MPA の場合、環境に関する新しい API は設定に公開されません。内部的には、Vite はオプションを client 環境に適用しますが、Vite を設定する際にこの概念を知る必要はありません。Vite 5 からの設定と動作は、ここでもシームレスに機能するはずです。

典型的なサーバーサイドレンダリング (SSR) アプリに移行すると、2 つの環境があります。

client: ブラウザでアプリを実行します。
ssr: Node (またはその他のサーバーランタイム) でアプリを実行し、ページをブラウザに送信する前にレンダリングします。

開発時には、Vite は Vite 開発サーバーと同じ Node プロセスでサーバーコードを実行し、本番環境に近い状態にします。ただし、サーバーは Cloudflare の workerd のように、異なる制約を持つ他の JS ランタイムで実行することも可能です。最新のアプリは、ブラウザ、Node サーバー、エッジサーバーなど、2 つ以上の環境で実行されることもあります。Vite 5 では、これらの環境を適切に表現できませんでした。

Vite 6 では、ユーザーはビルド中および開発中にアプリを設定して、すべての環境をマッピングできます。開発中、単一の Vite 開発サーバーで、複数の異なる環境でコードを同時に実行できるようになりました。アプリのソースコードは引き続き Vite 開発サーバーによって変換されます。共有 HTTP サーバー、ミドルウェア、解決された設定、およびプラグインパイプラインに加えて、Vite 開発サーバーは独立した開発環境のセットを持つようになりました。それぞれが本番環境に可能な限り一致するように設定されており、コードが実行される開発ランタイムに接続されています (workerd の場合、サーバーコードはローカルで miniflare で実行できるようになりました)。クライアントでは、ブラウザがコードをインポートして実行します。他の環境では、モジュールランナーが変換されたコードを取得して評価します。

Vite Environments

環境設定

SPA/MPA の場合、設定は Vite 5 と似ています。内部的には、これらのオプションは client 環境を設定するために使用されます。

export default defineConfig({
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
})

これは、Vite を使いやすく保ち、必要になるまで新しい概念を公開しないようにしたいので重要です。

アプリが複数の環境で構成されている場合、これらの環境は environments 設定オプションで明示的に設定できます。

export default {
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
  environments: {
    server: {},
    edge: {
      resolve: {
        noExternal: true,
      },
    },
  },
}

明示的に文書化されていない場合、環境は構成されたトップレベルの構成オプションを継承します (たとえば、新しい server および edge 環境は build.sourcemap: false オプションを継承します)。optimizeDeps など、少数のトップレベルオプションは client 環境にのみ適用されます。これは、サーバー環境のデフォルトとして適用するとうまく機能しないためです。client 環境は environments.client を介して明示的に構成することもできますが、新しい環境を追加する際にクライアントの構成が変更されないように、トップレベルのオプションを使用することをお勧めします。

EnvironmentOptions インターフェースは、環境ごとのすべてのオプションを公開します。resolve のように、build と dev の両方に適用される環境オプションがあります。また、開発およびビルド固有のオプション (dev.warmup や build.outDir など) には DevEnvironmentOptions と BuildEnvironmentOptions があります。optimizeDeps のような一部のオプションは開発にのみ適用されますが、後方互換性のために dev にネストせずにトップレベルに保持されています。

interface EnvironmentOptions {
  define?: Record<string, any>
  resolve?: EnvironmentResolveOptions
  optimizeDeps: DepOptimizationOptions
  consumer?: 'client' | 'server'
  dev: DevOptions
  build: BuildOptions
}

UserConfig インターフェースは EnvironmentOptions インターフェースを拡張しており、クライアントと、environments オプションを介して構成される他の環境のデフォルトを設定できます。client と ssr という名前のサーバー環境は、開発中に常に存在します。これにより、server.ssrLoadModule(url) および server.moduleGraph との後方互換性が維持されます。ビルド中、client 環境は常に存在し、ssr 環境は明示的に構成されている場合にのみ存在します (environments.ssr または後方互換性のために build.ssr を使用)。アプリは、SSR 環境に ssr という名前を使用する必要はなく、たとえば server と名付けることができます。

interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // other options
}

ssr トップレベルプロパティは、環境 API が安定すると非推奨になることに注意してください。このオプションは environments と同じ役割を持っていますが、デフォルトの ssr 環境専用であり、少数のオプションの構成のみを許可していました。

カスタム環境インスタンス

ランタイムプロバイダーが、ランタイムに適したデフォルト値を持つ環境を提供できるように、低レベルの構成 API が利用可能です。これらの環境は、開発中に本番環境に近いランタイムでモジュールを実行するために、他のプロセスやスレッドを生成することもできます。

import { customEnvironment } from 'vite-environment-provider'

export default {
  build: {
    outDir: '/dist/client',
  },
  environments: {
    ssr: customEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
  },
}

後方互換性

現在の Vite サーバー API はまだ非推奨になっておらず、Vite 5 と後方互換性があります。新しい環境 API は実験的です。

server.moduleGraph は、クライアントと ssr モジュールグラフの混合ビューを返します。後方互換性のある混合モジュールノードは、そのすべてのメソッドから返されます。handleHotUpdate に渡されるモジュールノードにも同じスキームが使用されます。

まだ環境 API に切り替えることはお勧めしません。プラグインが 2 つのバージョンを維持する必要がないように、ユーザーベースの大部分が Vite 6 を採用することを目標としています。将来の非推奨とアップグレードパスに関する情報は、将来の破壊的変更のセクションを参照してください。

対象ユーザー

このガイドは、エンドユーザー向けの環境に関する基本的な概念を提供します。

プラグインの作者は、現在の環境構成と対話するための、より一貫性のある API を利用できます。Vite の上に構築している場合、環境 API プラグインガイドでは、複数のカスタム環境をサポートするために利用できる拡張プラグイン API の方法について説明しています。

フレームワークは、異なるレベルで環境を公開することを決定する場合があります。フレームワークの作者の方は、環境 API フレームワークガイドを読み続けて、環境 API のプログラム的な側面について学んでください。

ランタイムプロバイダーの場合、環境 API ランタイムガイドでは、フレームワークやユーザーが利用できるカスタム環境を提供する方法について説明しています。

環境 API ​

環境の形式化 ​

ビルドと開発のギャップを埋める ​

環境設定 ​

カスタム環境インスタンス ​

後方互換性 ​

対象ユーザー ​