build()

Build your Astro site for production deployment

The build() function builds your Astro site for deployment. By default, this generates static files in a dist/ directory. If SSR is enabled, it generates the necessary server files.

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

Import

import { build } from 'astro';

Signature

function build(
  inlineConfig: AstroInlineConfig,
  options?: BuildOptions
): Promise<void>

Parameters

inlineConfig

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 during the build.

inlineConfig.site · string

Your final deployed URL. Used for generating sitemaps and canonical URLs.

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

The base path to deploy to. All pages and assets will use this as a prefix.

inlineConfig.outDir · string · default: "'./dist'"

The directory where build output will be written.

inlineConfig.mode · string · default: "'production'"

The build mode. Affects environment variable loading.

inlineConfig.force · boolean · default: "false"

Clear the content layer cache before building, forcing a full rebuild.

options

options · BuildOptions

Additional build-specific options.

options.devOutput · boolean · default: "false"

Output a development-based build similar to astro dev. Useful for testing build-only issues with additional debugging information.

options.teardownCompiler · boolean · default: "true"

Teardown the compiler WASM instance after build. Improves performance for single builds, but may hurt performance when building multiple times in succession (e.g., during tests).

Return Value

Returns a Promise<void> that resolves when the build completes successfully, or rejects with an error if the build fails.

Examples

Basic Build

import { build } from 'astro';

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

Custom Configuration

import { build } from 'astro';

await build({
  root: './my-project',
  site: 'https://example.com',
  base: '/blog',
  outDir: './dist/blog',
  logLevel: 'info',
});

Development Build

Create a build with development-like output for debugging:

import { build } from 'astro';

await build(
  {
    root: './my-project',
    logLevel: 'debug',
  },
  {
    devOutput: true,
  }
);

Multiple Builds

When building multiple projects, disable compiler teardown for better performance:

import { build } from 'astro';

const projects = ['./site-1', './site-2', './site-3'];

for (let i = 0; i < projects.length; i++) {
  await build(
    { root: projects[i] },
    {
      // Don't teardown compiler until the last build
      teardownCompiler: i === projects.length - 1,
    }
  );
}

With Error Handling

import { build } from 'astro';

try {
  await build({
    root: './my-project',
    site: 'https://example.com',
  });
  console.log('Build completed successfully!');
} catch (error) {
  console.error('Build failed:', error);
  process.exit(1);
}

Force Clean Build

import { build } from 'astro';

await build({
  root: './my-project',
  force: true, // Clear content layer cache
});

CI/CD Integration

import { build } from 'astro';

async function buildForProduction() {
  const startTime = Date.now();

  await build({
    root: process.env.PROJECT_ROOT || '.',
    site: process.env.SITE_URL,
    base: process.env.BASE_PATH || '/',
    outDir: process.env.OUT_DIR || './dist',
    logLevel: process.env.CI ? 'info' : 'debug',
  });

  const duration = ((Date.now() - startTime) / 1000).toFixed(2);
  console.log(`Build completed in ${duration}s`);
}

buildForProduction().catch((error) => {
  console.error('Build failed:', error);
  process.exit(1);
});

Related

• dev() - Start the development server
• preview() - Preview your production build
• sync() - Generate TypeScript types