> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.

# dev()

> Start the Astro development server with Hot Module Replacement

The `dev()` function starts Astro's development server. This is a local HTTP server that uses Hot Module Replacement (HMR) to update your browser as you save changes.

<Warning>
  The JavaScript API is experimental and may change in future releases.
</Warning>

## Import

```javascript theme={null}
import { dev } from 'astro';
```

## Signature

```typescript theme={null}
function dev(inlineConfig: AstroInlineConfig): Promise<DevServer>
```

## Parameters

<ParamField path="inlineConfig" type="AstroInlineConfig" required>
  Configuration object for your Astro project. Supports all options from `astro.config.mjs`.
</ParamField>

<ParamField path="inlineConfig.root" type="string">
  The root directory of your Astro project. Defaults to the current working directory.
</ParamField>

<ParamField path="inlineConfig.logLevel" type="'debug' | 'info' | 'warn' | 'error' | 'silent'" default="'info'">
  Controls the verbosity of logging output.
</ParamField>

<ParamField path="inlineConfig.site" type="string">
  Your site URL. Used for generating URLs during development.
</ParamField>

<ParamField path="inlineConfig.base" type="string" default="'/'">
  The base path your site is served from.
</ParamField>

<ParamField path="inlineConfig.server" type="object">
  Server configuration options.
</ParamField>

<ParamField path="inlineConfig.server.port" type="number" default="4321">
  The port the dev server listens on. If already in use, Astro will try the next available port.
</ParamField>

<ParamField path="inlineConfig.server.host" type="string | boolean" default="false">
  Set which network IP addresses the server listens on. Set to `true` to listen on all addresses including LAN and public addresses.
</ParamField>

<ParamField path="inlineConfig.server.open" type="string | boolean" default="false">
  Controls whether the dev server opens in your browser on startup. Pass a URL string or pathname to specify what to open.
</ParamField>

## Return Value

Returns a `Promise<DevServer>` that resolves to a server object with the following properties:

<ParamField path="address" type="AddressInfo">
  Information about the server's address, including port and host.
</ParamField>

<ParamField path="address.port" type="number">
  The port the server is listening on.
</ParamField>

<ParamField path="address.address" type="string">
  The address the server is listening on.
</ParamField>

<ParamField path="handle" type="(req, res) => void">
  Request handler function. Can be used to integrate with other Node.js servers.
</ParamField>

<ParamField path="watcher" type="FSWatcher">
  Vite's file system watcher instance. Can be used to watch for file changes.
</ParamField>

<ParamField path="stop" type="() => Promise<void>">
  Stops the dev server and cleans up resources.
</ParamField>

## Examples

### Basic Dev Server

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
});

console.log(`Server running at http://localhost:${server.address.port}`);
```

### Custom Port and Host

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
  server: {
    port: 3000,
    host: true, // Listen on all addresses
  },
});
```

### Auto-Open Browser

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
  server: {
    open: '/about', // Open the /about page
  },
});
```

### Silent Mode

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
  logLevel: 'silent',
});
```

### Integration Testing

```javascript theme={null}
import { dev } from 'astro';
import fetch from 'node-fetch';

let server;

before(async () => {
  server = await dev({
    root: './test-fixtures/basic',
    logLevel: 'silent',
    server: { port: 4567 },
  });
});

after(async () => {
  await server.stop();
});

it('should render homepage', async () => {
  const response = await fetch(`http://localhost:${server.address.port}`);
  const html = await response.text();
  expect(html).toContain('<h1>Welcome</h1>');
});
```

### File Watching

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
});

// Watch for file changes
server.watcher.on('change', (file) => {
  console.log(`File changed: ${file}`);
});

// Stop server after some time
setTimeout(async () => {
  await server.stop();
  console.log('Server stopped');
}, 60000);
```

### Custom Request Handling

```javascript theme={null}
import { dev } from 'astro';
import http from 'node:http';

const astroServer = await dev({
  root: './my-project',
  logLevel: 'silent',
});

// Create a custom HTTP server
const server = http.createServer((req, res) => {
  // Add custom logic before Astro handles the request
  if (req.url === '/custom') {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Custom response');
    return;
  }

  // Let Astro handle all other requests
  astroServer.handle(req, res);
});

server.listen(3000);
```

### Development with Custom Base Path

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
  base: '/docs',
  server: {
    port: 4321,
  },
});

console.log(`Server running at http://localhost:${server.address.port}/docs`);
```

### Graceful Shutdown

```javascript theme={null}
import { dev } from 'astro';

const server = await dev({
  root: './my-project',
});

// Handle shutdown signals
process.on('SIGINT', async () => {
  console.log('\nShutting down server...');
  await server.stop();
  process.exit(0);
});

process.on('SIGTERM', async () => {
  console.log('\nShutting down server...');
  await server.stop();
  process.exit(0);
});
```

## Related

* [build()](/api/build) - Build for production
* [preview()](/api/preview) - Preview production build
* [sync()](/api/sync) - Generate TypeScript types