CC 4.0 ライセンス

このセクションの内容は、以下のリンクの内容から派生したものであり、CC BY 4.0 ライセンスの対象となります。
https://webpack.dokyumento.jp/configuration/dev-server/
特に明記されていない限り、以下の内容は元のコンテンツに基づいて修正および削除された結果とみなすことができます。

DevServer

このページでは、`webpack-dev-server@5`に基づいた@rspack/dev-server（略称：dev-server）の動作に影響を与えるオプションについて説明します。dev-serverは、迅速なアプリケーション開発を促進します。

型: object

ヒント

現在のアプリケーションが`@rspack/dev-server`に依存していない場合、devServerの設定は無効になります。

たとえば、Rspack CLIはデフォルトで`@rspack/dev-server`に依存しているため、devServerの設定はRspack CLIプロジェクトで使用できます。Rsbuildは独自の開発サーバーを実装しており、別の「サーバー」設定を提供しているため、devServerの設定はRsbuildプロジェクトでは使用できません。

devServer.allowedHosts

型: string | string[] | 'all' | 'auto'
デフォルト: 'auto'

このオプションでは、開発サーバーへのアクセスを許可するサービスをホワイトリストに登録できます。

rspack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: [
      'host.com',
      'subdomain.host.com',
      'subdomain2.host.com',
      'host2.com',
    ],
  },
};

Djangoの`ALLOWED_HOSTS`を模倣して、`.`で始まる値をサブドメインのワイルドカードとして使用できます。`.host.com`は、`host.com`、`www.host.com`、および`host.com`の他のサブドメインと一致します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    // this achieves the same effect as the first example
    // with the bonus of not having to update your config
    // if new subdomains need to access the dev server
    allowedHosts: ['.host.com', 'host2.com'],
  },
};

`'all'`に設定すると、このオプションはホストチェックをバイパスします。ホストをチェックしないアプリはDNSリバインディング攻撃に対して脆弱であるため、これは推奨されません。

rspack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: 'all',
  },
};

`'auto'`に設定すると、このオプションは常に`localhost`、`host`、および`client.webSocketURL.hostname`を許可します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    allowedHosts: 'auto',
  },
};

devServer.client

型: object

ロギング

型: 'log' | 'info' | 'warn' | 'error' | 'none' | 'verbose'
デフォルト: 'info'

ブラウザでのログレベルを設定できます。たとえば、リロード前、エラー前、またはホットモジュールリプレースメントが有効になっている場合などです。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      logging: 'info',
    },
  },
};

オーバーレイ

型: boolean | object
デフォルト: true

コンパイラエラーまたは警告がある場合、ブラウザにフルスクリーンオーバーレイを表示します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: true,
    },
  },
};

よりきめ細かい制御のために、次のプロパティを持つオブジェクトを提供できます。

プロパティ	説明
`errors`	コンパイルエラー
`runtimeErrors`	処理されないランタイムエラー
`warnings`	コンパイル警告

すべてプロパティはオプションであり、指定しない場合はデフォルトで`true`になります。

たとえば、コンパイル警告を無効にするには、次の設定を提供できます。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: {
        errors: true,
        warnings: false,
        runtimeErrors: true,
      },
    },
  },
};

スローされたエラーに基づいてフィルタリングするには、`error`パラメータを受け取り、ブール値を返す関数を渡すことができます。

たとえば、`AbortController.abort()`によってスローされたエラーを無視するには、次のようにします。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      overlay: {
        runtimeErrors: error => {
          if (error instanceof DOMException && error.name === 'AbortError') {
            return false;
          }
          return true;
        },
      },
    },
  },
};

警告

関数は、設定ファイル内の外側のスコープで宣言された変数にアクセスできません。

progress

型: boolean
デフォルト: true

ブラウザにコンパイルの進捗状況をパーセントで表示します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      progress: true,
    },
  },
};

reconnect

型: `boolean | number`
デフォルト: true

dev-serverに、クライアントの再接続を試行する回数を指示します。`true`の場合、無制限に再接続を試みます。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: true,
    },
  },
};

`false`に設定すると、再接続を試みません。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: false,
    },
  },
};

クライアントが再接続を試行する正確な回数を指定することもできます。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      reconnect: 5,
    },
  },
};

webSocketTransport

種類: 'ws' | 'sockjs'
デフォルト: ws

このオプションを使用すると、現在のdevServerのトランスポートモードをクライアントごとに選択したり、カスタムクライアント実装を提供したりできます。これにより、ブラウザまたは他のクライアントがdevServerと通信する方法を指定できます。

ヒント

webSocketServerに'ws'または'sockjs'を提供すると、devServer.client.webSocketTransportとdevServer.webSocketServerの両方が指定された値に設定されます。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: 'ws',
    },
    webSocketServer: 'ws',
  },
};

ヒント

カスタムクライアントとサーバーの実装を提供する場合は、それらが互いに互換性があり、正常に通信できるようにしてください。

カスタムクライアント実装を作成するには、BaseClientを拡張するクラスを作成します。

互換性のある'ws'サーバーと共に、カスタムWebSocketクライアント実装であるCustomClient.jsへのパスを使用する

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: 'ws',
  },
};

互換性のあるカスタムWebSocketクライアントとサーバーの実装を使用する

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};

webSocketURL

種類: string | object
デフォルト: {}

このオプションを使用すると、WebSocketサーバーへのURLを指定できます（開発サーバーをプロキシしていて、クライアントスクリプトがどこに接続するかを常に認識していない場合に便利です）。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketURL: 'ws://0.0.0.0:8080/ws',
    },
  },
};

次のプロパティを持つオブジェクトを指定することもできます

hostname: devServerに接続されているクライアントに、指定されたホスト名を使用するように指示します。
pathname: devServerに接続されているクライアントに、接続に指定されたパスを使用するように指示します。
password: devServerに接続されているクライアントに、認証に指定されたパスワードを使用するように指示します。
port: devServerに接続されているクライアントに、指定されたポートを使用するように指示します。
protocol: devServerに接続されているクライアントに、指定されたプロトコルを使用するように指示します。
username: devServerに接続されているクライアントに、認証に指定されたユーザー名を使用するように指示します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    client: {
      webSocketURL: {
        hostname: '0.0.0.0',
        pathname: '/ws',
        password: 'dev-server',
        port: 8080,
        protocol: 'ws',
        username: 'rspack',
      },
    },
  },
};

ヒント

ブラウザからprotocol/hostname/portを取得するには、webSocketURL: 'auto://0.0.0.0:0/ws'を使用します。

devServer.compress

型: boolean
デフォルト: true

提供されるすべてのリソースに対してgzip圧縮を有効にします

rspack.config.js

module.exports = {
  //...
  devServer: {
    compress: true,
  },
};

devServer.devMiddleware

型: object
デフォルト: {}

Rspackアセットを処理するwebpack-dev-middlewareにオプションを提供します。

rspack.config.js

module.exports = {
  devServer: {
    devMiddleware: {
      index: true,
      mimeTypes: { phtml: 'text/html' },
      publicPath: '/publicPathForDevServe',
      serverSideRender: true,
      writeToDisk: true,
    },
  },
};

devServer.headers

種類: array | function | object
デフォルト: undefined

すべてのリスポンスにヘッダーを追加します

rspack.config.js

module.exports = {
  //...
  devServer: {
    headers: {
      'X-Custom-Foo': 'bar',
    },
  },
};

配列を渡すこともできます

rspack.config.js

module.exports = {
  //...
  devServer: {
    headers: [
      {
        key: 'X-Custom',
        value: 'foo',
      },
      {
        key: 'Y-Custom',
        value: 'bar',
      },
    ],
  },
};

関数を渡すこともできます

rspack.config.js

module.exports = {
  //...
  devServer: {
    headers: () => {
      return { 'X-Bar': ['key1=value1', 'key2=value2'] };
    },
  },
};

devServer.historyApiFallback

型: boolean | object
デフォルト: false

HTML5 History APIを使用する場合、404レスポンスの代わりにindex.htmlページを提供する必要がある場合があります。devServer.historyApiFallbackをtrueに設定して有効にします

rspack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: true,
  },
};

オブジェクトを提供することにより、rewritesなどのオプションを使用してこの動作をさらに制御できます

rspack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: {
      rewrites: [
        { from: /^\/$/, to: '/views/landing.html' },
        { from: /^\/subpage/, to: '/views/subpage.html' },
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};

パスにドットを使用する場合（Angularで一般的）、disableDotRuleを使用する必要がある場合があります

rspack.config.js

module.exports = {
  //...
  devServer: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};

その他のオプションと情報については、connect-history-api-fallbackのドキュメントを参照してください。

devServer.host

種類: 'local-ip' | 'local-ipv4' | 'local-ipv6' | string
デフォルト: 'local-ip'

使用するホストを指定します。サーバーを外部からアクセスできるようにするには、次のように指定します

rspack.config.js

module.exports = {
  //...
  devServer: {
    host: '0.0.0.0',
  },
};

local-ip

ホストとしてlocal-ipを指定すると、ホストオプションをローカルのIPv4アドレスとして解決しようとします（利用可能な場合）。IPv4が利用できない場合は、ローカルのIPv6アドレスを解決しようとします。

local-ipv4

ホストとしてlocal-ipv4を指定すると、ホストオプションをローカルのIPv4アドレスとして解決しようとします。

local-ipv6

ホストとしてlocal-ipv6を指定すると、ホストオプションをローカルのIPv6アドレスとして解決しようとします。

devServer.hot

種類: boolean | 'only'
デフォルト: true

Rspackのホットモジュール置換機能を有効にします

rspack.config.js

module.exports = {
  //...
  devServer: {
    hot: true,
  },
};

ビルドエラーが発生した場合のフォールバックとして、ページを更新せずにホットモジュール置換を有効にするには、hot: 'only'を使用します

rspack.config.js

module.exports = {
  //...
  devServer: {
    hot: 'only',
  },
};

devServer.liveReload

型: boolean
デフォルト: true

デフォルトでは、ファイルの変更が検出されると、dev-serverはページをリロード/更新します。liveReloadを有効にするには、devServer.hotオプションを無効にするか、devServer.watchFilesオプションを有効にする必要があります。devServer.liveReloadをfalseに設定して無効にします

rspack.config.js

module.exports = {
  //...
  devServer: {
    liveReload: false,
  },
};

ヒント

ライブリロードは、web、webworker、electron-renderer、node-webkitなどのWeb関連のターゲットでのみ機能します。

devServer.onListening

種類: function (devServer)

@rspack/dev-serverがポートで接続のリスニングを開始したときに、カスタム関数を実行する機能を提供します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    onListening: function (devServer) {
      if (!devServer) {
        throw new Error('@rspack/dev-server is not defined');
      }

      const port = devServer.server.address().port;
      console.log('Listening on port:', port);
    },
  },
};

devServer.open

種類: boolean | string | object | [string, object]
デフォルト: true

サーバーの起動後にブラウザを開くようにdev-serverに指示します。デフォルトのブラウザを開くには、trueに設定します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    open: true,
  },
};

ブラウザで指定されたページを開くには

rspack.config.js

module.exports = {
  //...
  devServer: {
    open: ['/my-page'],
  },
};

ブラウザで複数の指定されたページを開くには

rspack.config.js

module.exports = {
  //...
  devServer: {
    open: ['/my-page', '/another-page'],
  },
};

デフォルトのブラウザの代わりに使用するブラウザ名を指定します

rspack.config.js

module.exports = {
  //...
  devServer: {
    open: {
      app: {
        name: 'google-chrome',
      },
    },
  },
};

オブジェクトはすべてのopenオプションを受け入れます

rspack.config.js

module.exports = {
  //...
  devServer: {
    open: {
      target: ['first.html', 'http://localhost:8080/second.html'],
      app: {
        name: 'google-chrome',
        arguments: ['--incognito', '--new-window'],
      },
    },
  },
};

ヒント

ブラウザアプリケーション名はプラットフォームによって異なります。再利用可能なモジュールでハードコーディングしないでください。たとえば、'Chrome'はmacOSでは'Google Chrome'、Linuxでは'google-chrome'、Windowsでは'chrome'です。

devServer.port

種類: 'auto' | string | number
デフォルト: []

リクエストをリスニングするポート番号を指定します

rspack.config.js

module.exports = {
  //...
  devServer: {
    port: 8080,
  },
};

portオプションはnullまたは空の文字列にすることはできません。空きポートを自動的に使用するには、port: 'auto'を使用してください

rspack.config.js

module.exports = {
  //...
  devServer: {
    port: 'auto',
  },
};

devServer.proxy

種類: [object, function]

ヒント

Rspackの@rspack/dev-serverはwebpack-dev-server v5を使用しており、devServer.proxyは配列型です。使用している構成がv4バージョンのオブジェクト型の場合、最初にwebpack-dev-server/migration-v5.mdの移行に従って移行する必要があります。

一部のURLをプロキシすることは、別のAPIバックエンド開発サーバーがあり、同じドメインでAPIリクエストを送信する場合に役立ちます。

dev-serverは強力なhttp-proxy-middlewareパッケージを利用しています。より高度な使用方法については、そのドキュメントを確認してください。http-proxy-middlewareの機能の一部はtargetキーを必要としません（たとえば、router機能）。ただし、ここでも構成にtargetキーを含める必要があります。そうしないと、@rspack/dev-serverはそれをhttp-proxy-middlewareに渡しません。

localhost:3000のバックエンドでは、これを使用してプロキシを有効にできます

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};

/api/usersへのリクエストは、リクエストをhttp://localhost:3000/api/usersにプロキシするようになります。

/apiを渡したくない場合は、パスを書き換える必要があります

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        pathRewrite: { '^/api': '' },
      },
    ],
  },
};

無効な証明書でHTTPSで実行されているバックエンドサーバーは、デフォルトでは受け入れられません。必要な場合は、次のように構成を変更します

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        secure: false,
      },
    ],
  },
};

すべてをプロキシしたくない場合があります。関数の戻り値に基づいてプロキシをバイパスすることができます。

関数では、リクエスト、レスポンス、およびプロキシオプションにアクセスできます。

プロキシでリクエストの処理を続行するには、nullまたはundefinedを返します。
リクエストに対して404エラーを生成するには、falseを返します。
リクエストのプロキシを続行する代わりに、提供するパスを返します。

たとえば、ブラウザリクエストの場合はHTMLページを提供したいが、APIリクエストの場合はプロキシしたいとします。次のようなことができます

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        bypass: function (req, res, proxyOptions) {
          if (req.headers.accept.indexOf('html') !== -1) {
            console.log('Skipping proxy for browser request.');
            return '/index.html';
          }
        },
      },
    ],
  },
};

複数の特定のパスを同じターゲットにプロキシする場合は、contextプロパティを持つ1つ以上のオブジェクトの配列を使用できます

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/auth', '/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};

ルートへのリクエストはデフォルトではプロキシされません。ルートプロキシを有効にするには、devMiddleware.indexオプションをfalsy値として指定する必要があります

rspack.config.js

module.exports = {
  //...
  devServer: {
    devMiddleware: {
      index: false, // specify to enable root proxying
    },
    proxy: [
      {
        context: () => true,
        target: 'http://localhost:1234',
      },
    ],
  },
};

ホストヘッダーのoriginはデフォルトでプロキシ時に保持されます。この動作をオーバーライドするには、changeOriginをtrueに設定できます。名前ベースのバーチャルホストサイトを使用する場合などに便利です。

rspack.config.js

module.exports = {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        changeOrigin: true,
      },
    ],
  },
};

devServer.server

種類: 'http' | 'https' | 'spdy' | string | object
デフォルト: 'http'

サーバーとオプションを設定できます（デフォルトは「http」）。

rspack.config.js

module.exports = {
  //...
  devServer: {
    server: 'http',
  },
};

自己署名証明書を使用してHTTPS経由で提供するには

rspack.config.js

module.exports = {
  //...
  devServer: {
    server: 'https',
  },
};

自己署名証明書を使用してspdyでHTTP/2経由で提供するには

rspack.config.js

module.exports = {
  //...
  devServer: {
    server: 'spdy',
  },
};

オブジェクト構文を使用して独自の証明書を提供します

rspack.config.js

module.exports = {
  //...
  devServer: {
    server: {
      type: 'https',
      options: {
        ca: './path/to/server.pem',
        pfx: './path/to/server.pfx',
        key: './path/to/server.key',
        cert: './path/to/server.crt',
        passphrase: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};

また、minVersionなどの追加のTLSオプションを設定することもでき、それぞれのファイルの内容を直接渡すこともできます

rspack.config.js

const fs = require('fs');
const path = require('path');

module.exports = {
  //...
  devServer: {
    server: {
      type: 'https',
      options: {
        minVersion: 'TLSv1.1',
        key: fs.readFileSync(path.join(__dirname, './server.key')),
        pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
        cert: fs.readFileSync(path.join(__dirname, './server.crt')),
        ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
        passphrase: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};

devServer.setupMiddlewares

種類: function (middlewares, devServer)

カスタム関数を実行し、カスタムミドルウェアを適用する機能を提供します。

rspack.config.js

module.exports = {
  // ...
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      if (!devServer) {
        throw new Error('@rspack/dev-server is not defined');
      }

      devServer.app.get('/setup-middleware/some/path', (_, response) => {
        response.send('setup-middlewares option GET');
      });

      // Use the `unshift` method if you want to run a middleware before all other middlewares
      // or when you are migrating from the `onBeforeSetupMiddleware` option
      middlewares.unshift({
        name: 'first-in-array',
        // `path` is optional
        path: '/foo/path',
        middleware: (req, res) => {
          res.send('Foo!');
        },
      });

      // Use the `push` method if you want to run a middleware after all other middlewares
      // or when you are migrating from the `onAfterSetupMiddleware` option
      middlewares.push({
        name: 'hello-world-test-one',
        // `path` is optional
        path: '/foo/bar',
        middleware: (req, res) => {
          res.send('Foo Bar!');
        },
      });

      middlewares.push((req, res) => {
        res.send('Hello World!');
      });

      return middlewares;
    },
  },
};

devServer.static

種類: boolean | string | object | [string, object]

このオプションを使用すると、ディレクトリ（デフォルトでは「public」ディレクトリ）から静的ファイルを提供するためのオプションを構成できます。無効にするには、falseに設定します

rspack.config.js

module.exports = {
  //...
  devServer: {
    static: false,
  },
};

単一のディレクトリを監視するには

rspack.config.js

module.exports = {
  // ...
  devServer: {
    static: ['assets'],
  },
};

複数の静的ディレクトリを監視するには

rspack.config.js

module.exports = {
  // ...
  devServer: {
    static: ['assets', 'css'],
  },
};

devServer.watchFiles

型: string | object | [string, object]

このオプションでは、ファイルの変更を監視する glob/ディレクトリ/ファイルのリストを設定できます。例えば

rspack.config.js

module.exports = {
  //...
  devServer: {
    watchFiles: ['src/**/*.php', 'public/**/*'],
  },
};

ファイル監視の詳細オプションを設定することも可能です。chokidar のドキュメントで、使用可能なオプションを確認してください。

rspack.config.js

module.exports = {
  //...
  devServer: {
    watchFiles: {
      paths: ['src/**/*.php', 'public/**/*'],
      options: {
        usePolling: false,
      },
    },
  },
};

devServer.webSocketServer

型: false | 'sockjs' | 'ws'

このオプションを使用すると、現在の WebSocket サーバーを選択するか、カスタム WebSocket サーバー実装を提供することができます。

現在のデフォルトモードは 'ws' です。このモードは、サーバーとして ws を使用し、クライアントではネイティブ WebSocket を使用します。

rspack.config.js

module.exports = {
  //...
  devServer: {
    webSocketServer: 'ws',
  },
};

DevServer#

devServer.allowedHosts#

devServer.client#

ロギング#

オーバーレイ#

progress#

reconnect#

webSocketTransport#

webSocketURL#

devServer.compress#

devServer.devMiddleware#

devServer.headers#

devServer.historyApiFallback#

devServer.host#

local-ip#

local-ipv4#

local-ipv6#

devServer.hot#

devServer.liveReload#

devServer.onListening#

devServer.open#

devServer.port#

devServer.proxy#

devServer.server#

devServer.setupMiddlewares#

devServer.static#

devServer.watchFiles#

devServer.webSocketServer#

DevServer

devServer.allowedHosts

devServer.client

ロギング

オーバーレイ

progress

reconnect

webSocketTransport

webSocketURL

devServer.compress

devServer.devMiddleware

devServer.headers

devServer.historyApiFallback

devServer.host

local-ip

local-ipv4

local-ipv6

devServer.hot

devServer.liveReload

devServer.onListening

devServer.open

devServer.port

devServer.proxy

devServer.server

devServer.setupMiddlewares

devServer.static

devServer.watchFiles

devServer.webSocketServer