Programmatic Astro API (experimental)

If you need more control when running Astro, the "astro" package exports APIs to programmatically run the CLI commands.

These APIs are experimental and their API signature may change. Any updates will be mentioned in the Astro changelog and the information below will always show the current, up-to-date information.

AstroInlineConfig

Section titled AstroInlineConfig

The AstroInlineConfig type is used by all of the command APIs below. It extends from the user Astro config type:

interface AstroInlineConfig extends AstroUserConfig {
  configFile?: string | false;
  mode?: string;
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

configFile

Section titled configFile

Type: string | false
Default: undefined

A custom path to the Astro config file.

If this value is undefined (default) or unset, Astro will search for an astro.config.(js,mjs,ts,mts) file relative to the root and load the config file if found.

If a relative path is set, it will resolve based on the root option.

Set to false to disable loading any config files.

The inline config passed in this object will take highest priority when merging with the loaded user config.

mode

Section titled mode

Type: string
Default: "development" when running astro dev, "production" when running astro build

Added in: astro@5.0.0 New

The mode used when developing or building your site (e.g. "production", "testing").

This value is passed to Vite using the --mode flag when the astro build or astro dev commands are run to determine the value of import.meta.env.MODE. This also determines which .env files are loaded, and therefore the values of astro:env. See the environment variables page for more details.

To output a development-based build, you can run astro build with the --devOutput flag.

logLevel

Section titled logLevel

Type: "debug" | "info" | "warn" | "error" | "silent"
Default: "info"

The logging level to filter messages logged by Astro.

• "debug": Log everything, including noisy debugging diagnostics.
• "info": Log informational messages, warnings, and errors.
• "warn": Log warnings and errors.
• "error": Log errors only.
• "silent": No logging.

dev()

Section titled dev()

Type: (inlineConfig: AstroInlineConfig) => Promise<DevServer>

Similar to astro dev, it runs Astro’s development server.

import { dev } from "astro";

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

// Stop the server if needed
await devServer.stop();

DevServer

Section titled DevServer

export interface DevServer {
  address: AddressInfo;
  handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
  watcher: vite.FSWatcher;
  stop(): Promise<void>;
}

address

Section titled address

Type: AddressInfo

The address the dev server is listening on.

This property contains the value returned by Node’s net.Server#address() method.

handle()

Section titled handle()

Type: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void

A handle for raw Node HTTP requests. You can call handle() with an http.IncomingMessage and an http.ServerResponse instead of sending a request through the network.

watcher

Section titled watcher

Type: vite.FSWatcher

The Chokidar file watcher as exposed by Vite’s development server.

stop()

Section titled stop()

Type: Promise<void>

Stops the development server. This closes all idle connections and stops listening for new connections.

Returns a Promise that resolves once all pending requests have been fulfilled and all idle connections have been closed.

build()

Section titled build()

Type: (inlineConfig: AstroInlineConfig) => Promise<void>

Similar to astro build, it builds your site for deployment.

import { build } from "astro";

await build({
  root: "./my-project",
});

preview()

Section titled preview()

Type: (inlineConfig: AstroInlineConfig) => Promise<PreviewServer>

Similar to astro preview, it starts a local server to serve your build output.

If no adapter is set in the configuration, the preview server will only serve the built static files. If an adapter is set in the configuration, the preview server is provided by the adapter. Adapters are not required to provide a preview server, so this feature may not be available depending on your adapter of choice.

import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// Stop the server if needed
await previewServer.stop();

PreviewServer

Section titled PreviewServer

export interface PreviewServer {
  host?: string;
  port: number;
  closed(): Promise<void>;
  stop(): Promise<void>;
}

host

Section titled host

Type: string

The host where the server is listening for connections.

Adapters are allowed to leave this field unset. The value of host is implementation-specific.

port

Section titled port

Type: number

The port where the server is listening for connections.

stop()

Section titled stop()

Type: Promise<void>

Asks the preview server to close, stop accepting requests, and drop idle connections.

The returned Promise resolves when the close request has been sent. This does not mean that the server has closed yet. Use the closed() method if you need to ensure the server has fully closed.

closed()

Section titled closed()

Type: Promise<void>

Returns a Promise that will resolve once the server is closed and reject if an error happens on the server.

sync()

Section titled sync()

Type: (inlineConfig: AstroInlineConfig) => Promise<void>

Similar to astro sync, it generates TypeScript types for all Astro modules.

import { sync } from "astro";

await sync({
  root: "./my-project",
});