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.

The JavaScript API is experimental and may change in future releases.

Import

import { dev } from 'astro';

Signature

function dev(inlineConfig: AstroInlineConfig): Promise<DevServer>

Parameters

inlineConfig · AstroInlineConfig · required

Configuration object for your Astro project. Supports all options from astro.config.mjs.

inlineConfig.root · string

The root directory of your Astro project. Defaults to the current working directory.

inlineConfig.logLevel · 'debug' | 'info' | 'warn' | 'error' | 'silent' · default: "'info'"

Controls the verbosity of logging output.

inlineConfig.site · string

Your site URL. Used for generating URLs during development.

inlineConfig.base · string · default: "'/'"

The base path your site is served from.

inlineConfig.server · object

Server configuration options.

inlineConfig.server.port · number · default: "4321"

The port the dev server listens on. If already in use, Astro will try the next available port.

inlineConfig.server.host · 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.

inlineConfig.server.open · 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.

Return Value

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

address · AddressInfo

Information about the server’s address, including port and host.

address.port · number

The port the server is listening on.

address.address · string

The address the server is listening on.

handle · (req, res) => void

Request handler function. Can be used to integrate with other Node.js servers.

watcher · FSWatcher

Vite’s file system watcher instance. Can be used to watch for file changes.

stop · () => Promise<void>

Stops the dev server and cleans up resources.

Examples

Basic Dev Server

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

import { dev } from 'astro';

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

Auto-Open Browser

import { dev } from 'astro';

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

Silent Mode

import { dev } from 'astro';

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

Integration Testing

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

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

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

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

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() - Build for production
• preview() - Preview production build
• sync() - Generate TypeScript types