Skip to main content
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);
});

Build docs developers (and LLMs) love

Get started for freeTalk to us