Advanced CLI Commands (experimental)

If you need more control when running Astro, the "astro" package also 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

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?: "development" | "production";
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

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

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

The mode used when building your site to generate either “development” or “production” code.

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()

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

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

address

The address the dev server is listening on.

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

handle()

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

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

stop()

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()

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()

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

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

host

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

The port where the server is listening for connections.

stop()

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()

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

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",
});