---
title: "Dev Server Options"
locale: "en"
version: "current"
canonicalUrl: "https://farmfe.org/docs/config/dev-server"
publicationStatus: "prerelease"
---

<a id="dev-server-options"></a>
# Dev Server Options


<a id="devserver-options--server"></a>
## DevServer Options - server


Configure the behavior of Farm Dev Server. Example:


```ts
import { defineConfig } from "@farmfe/core";

export default defineConfig({
  // All dev server options are under server
  server: {
    port: 9000,
    //...
  },
});
```


type:


```ts
export interface UserServerConfig {
  headers?: OutgoingHttpHeaders | undefined;
  port?: number;
  https?: HttpsServerOptions;
  origin?: string;
  allowedHosts?: string[];
  hmr?: boolean | HmrOptions;
  proxy?: Record<string, ProxyOptions>;
  strictPort?: boolean;
  open?: boolean;
  host?: string | boolean;
  cors?: boolean | any;
  appType?: 'spa' | 'mpa' | 'custom';
  middlewares?: DevServerMiddleware[];
  middlewareMode?: boolean;
  writeToDisk?: boolean;
  preview?: UserPreviewServerConfig;
}
```


<a id="port"></a>
### port


- **default**: ` 9000 `


The port the DevServer listens on.


<a id="https"></a>
### https


- **default**: ` undefined `


Enable  TLS  + HTTP2. The value is [options](<https://nodejs.org/api/http2.html#http2createsecureserveroptions-onrequesthandler>) that passes to [http2.createSecureServer](<https://nodejs.org/api/http2.html#http2createsecureserveroptions-onrequesthandler>).



> [!NOTE]
> note
> 
> Note that a **valid certificate** is needed if ` https ` enabled.



<a id="headers"></a>
### headers


- **default**: ` undefined `


Setup global http response headers for the DevServer.


```ts
import { defineConfig } from '@farmfe/core'

export default defineConfig({
  server: {
    headers: {
      'Accept': 'xxxx'
    }
  }
})
```


<a id="strictport"></a>
### strictPort


- **default**: ` false `


By default, Farm will automatically resolve to a new port when given port is used. For example, if ` 9001 ` is used, then ` 9001 ` will be tried. But if ` strictPort ` is ` true `, a error will be thrown when port conflicts, instead of try other ports automatically.


<a id="cors"></a>
### cors


- **default**: ` false `


Whether to enable CORS (Cross-Origin Resource Sharing) for the dev server.


<a id="apptype"></a>
### appType


- **default**: ` 'spa' `


Configure the application type, which affects how the dev server handles fallback routing:


- ` 'spa' `: Single Page Application. The server will fall back to ` index.html ` for unmatched routes.
- ` 'mpa' `: Multi-Page Application. The server will look for corresponding HTML files for each route.
- ` 'custom' `: Disable automatic HTML fallback. Useful when you have custom server-side logic.


<a id="hmr"></a>
### hmr


- **default**: ` true ` for start command, false for other commands


Enable HMR. After enabling the HMR capability, it will monitor the changes of the modules involved in the compilation process. When the modules change, it will automatically trigger recompilation and push the results to Farm Runtime for update. HMR can also be configured through an object, for example:


```ts
import { defineConfig } from '@farmfe/core';

export default defineConfig({
   // All dev server options are under server
   server: {
     hmr: {
       // Configure the port for web socket listening
       port: 9802,
       // Configure the host for web socket listening
       host: 'localhost',
       // The path for the HMR endpoint
       path: '/__hmr',
     }
     //...
   }
});
```


<a id="hmrport"></a>
#### ` hmr.port `


- **default**: ` undefined ` (falls back to ` FARM_DEFAULT_HMR_PORT ` env var, or the dev server port)


The port the WebSocket server listens on.


<a id="hmrhost"></a>
#### ` hmr.host `


- **default**: ` localhost `


Host on which the WebSocket server listens.


<a id="hmrclientport"></a>
#### ` hmr.clientPort `


- **default**: ` 9000 `


The port number for the HMR client to connect to. Useful when you have a reverse proxy in front of the dev server.


<a id="hmrpath"></a>
#### ` hmr.path `


- **default**: ` '/__hmr' `


The URL path for the HMR WebSocket endpoint.


<a id="hmrtimeout"></a>
#### ` hmr.timeout `


- **default**: ` 0 `


The timeout in milliseconds for the HMR WebSocket connection.


<a id="hmroverlay"></a>
#### ` hmr.overlay `


- **default**: ` true `


Whether to show an error overlay in the browser when HMR errors occur.


<a id="hmrprotocol"></a>
#### ` hmr.protocol `


- **default**: ` '' ` (auto-detected)


The WebSocket protocol to use for the HMR connection (e.g. ` 'ws' ` or ` 'wss' `).


<a id="proxy"></a>
### proxy


- **Default value**: ` undefined `


Configure server proxy. farm uses ` http-proxy ` as a proxy for the development server. Based on [http-proxy](<https://github.com/http-party/node-http-proxy?tab=readme-ov-file#options>) implementation, specific options refer to its documentation, example:


```ts
import { defineConfig } from "@farmfe/core";

export default defineConfig({
  server: {
    proxy: {
      "/api": {
        target: "https://music-erkelost.vercel.app/banner",
        changeOrigin: true,
        pathRewrite: (path: any) => path.replace(/^\/api/, ""),
      },
    },
  },
});
```


<a id="open"></a>
### open


- **default**: ` false `


After the compilation is completed, the browser is automatically opened to the corresponding page.


<a id="host"></a>
### host


- **default**: ` localhost `


The host that the Dev Server listens on.


<a id="middlewares"></a>
### middlewares


- **default**: ` [] `


Configuring middlewares for the dev server. A middleware is a function that receives the ` Server ` instance and returns a [connect](<https://github.com/senchalabs/connect>)-compatible middleware function.


```ts
import { defineConfig } from "@farmfe/core";

export default defineConfig({
  server: {
    middlewares: [
      (server) => {
        return (req, res, next) => {
          // custom middleware logic
          next();
        };
      },
    ],
  },
});
```


<a id="middlewaremode"></a>
### middlewareMode


- **default**: ` false `


Whether to run the server in middleware mode. When ` true `, the dev server will not start its own HTTP server, which is useful when you want to integrate Farm into an existing server framework.


<a id="origin"></a>
### origin


- **default**: ` '' `


The origin address of the server, used to configure the origin of the dev server in the response.


<a id="allowedhosts"></a>
### allowedHosts


- **default**: ` [] `


A list of allowed hostnames for the dev server. When configured, only requests with a ` Host ` header matching an entry in this list will be served.


<a id="writetodisk"></a>
### writeToDisk


- **default**: ` false `


By default the compiled resources are stored and served in memory, set ` writeToDisk ` to ` true ` to emit dev resources to the disk.


<a id="preview-server-options--serverpreview"></a>
## Preview Server Options - server.preview


Configure the preview server (used with ` farm preview `). Preview-specific options are nested under ` server.preview `.


```ts
export interface UserPreviewServerConfig {
  headers?: OutgoingHttpHeaders | false | undefined;
  host?: string | boolean;
  port?: number;
  strictPort?: boolean;
  https?: SecureServerOptions;
  distDir?: string;
  open?: boolean | string;
  cors?: boolean | any;
  proxy?: Record<string, ProxyOptions>;
  middlewares?: PreviewServerMiddleware[];
}
```


<a id="previewport"></a>
### ` preview.port `


- **default**: ` 1911 `


The port the preview server listens on.


<a id="previewhost"></a>
### ` preview.host `


- **default**: ` 'localhost' `


The host to run the preview server on.


<a id="previewstrictport"></a>
### ` preview.strictPort `


- **default**: ` false `


Whether to strictly use the specified port. If the port is occupied and this is ` true `, an error will be thrown.


<a id="previewdistdir"></a>
### ` preview.distDir `


- **default**: ` 'dist' `


Specify where the built output directory is located. If not specified, Farm resolves it from ` compilation.output.path `. If the path is relative, it is relative to ` root `.


<a id="previewopen"></a>
### ` preview.open `


- **default**: ` false `


Automatically open the preview server in the default browser.


<a id="previewhttps"></a>
### ` preview.https `


- **default**: inherits from ` server.https `


Secure server options for the preview server. Set to ` false ` to disable HTTPS for preview.


<a id="previewheaders"></a>
### ` preview.headers `


- **default**: inherits from ` server.headers `


HTTP headers to send with every preview server response. Set to ` false ` to disable.


<a id="previewproxy"></a>
### ` preview.proxy `


- **default**: inherits from ` server.proxy `


Proxy options for the preview server. Set to ` false ` to disable proxy.


<a id="previewmiddlewares"></a>
### ` preview.middlewares `


- **default**: ` [] `


Middlewares for the preview server, similar to ` server.middlewares `.
