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.
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.
Your final deployed URL. Used for generating sitemaps and canonical URLs.
The base path to deploy to. All pages and assets will use this as a prefix.
The directory where build output will be written.
inlineConfig.mode
string
default:"'production'"
The build mode. Affects environment variable loading.
Clear the content layer cache before building, forcing a full rebuild.
options
Additional build-specific options.
Output a development-based build similar to astro dev. Useful for testing build-only issues with additional debugging information.
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);
});
- dev() - Start the development server
- preview() - Preview your production build
- sync() - Generate TypeScript types