環境 API

実験的

環境 API は実験的です。エコシステムが実験し、その上に構築できるように、Vite 6 では API を安定させます。Vite 7 では、これらの新しい API を安定させる予定ですが、破壊的な変更の可能性があります。

リソース

• フィードバックに関する議論 新しい API に関するフィードバックを収集しています。
• 環境 API のプルリクエスト 新しい API が実装され、レビューされた場所です。

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

環境の公式化

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

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

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

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

• client: ブラウザでアプリケーションを実行します。
• server: ページをブラウザに送信する前にレンダリングするノード (または他のサーバーランタイム) でアプリケーションを実行します。

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

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

環境設定

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
}

環境 API が安定したら、トップレベルのプロパティである `ssr` は非推奨になることに注意してください。このオプションは `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 を採用することを目指しています。今後の非推奨事項とアップグレードパスについては、今後の破壊的変更のセクションをご覧ください。

• フックにおける `this.environment`
• HMR `hotUpdate` プラグインフック
• 環境ごとの API への移行
• `ModuleRunner` API を使用した SSR
• ビルド中の共有プラグイン

対象ユーザー

このガイドでは、エンドユーザー向けの環境に関する基本的な概念について説明します。

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

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

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