> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript API

> Use Astro programmatically with the JavaScript API

Astro provides a programmatic JavaScript API that allows you to run Astro commands from code. This is useful for building tools, integrations, or custom workflows.

<Warning>
  The JavaScript API is experimental and may change in future releases.
</Warning>

## Available Functions

The Astro JavaScript API exports the following functions:

<CardGroup cols={2}>
  <Card title="build()" icon="hammer" href="/api/build">
    Build your Astro project for production
  </Card>

  <Card title="dev()" icon="code" href="/api/dev">
    Start the Astro development server
  </Card>

  <Card title="preview()" icon="eye" href="/api/preview">
    Preview your production build locally
  </Card>

  <Card title="sync()" icon="arrows-rotate" href="/api/sync">
    Generate TypeScript types for your project
  </Card>
</CardGroup>

## Installation

Install Astro in your project:

```bash theme={null}
npm install astro
```

## Basic Usage

Import the functions you need from the `astro` package:

```javascript theme={null}
import { build, dev, preview, sync } from 'astro';

// Build your site
await build({ root: './my-project' });

// Start dev server
const server = await dev({ root: './my-project' });

// Preview production build
const previewServer = await preview({ root: './my-project' });

// Sync types
await sync({ root: './my-project' });
```

## Configuration

All API functions accept an `AstroInlineConfig` object that allows you to configure Astro programmatically. This object supports all the same options as `astro.config.mjs`.

```javascript theme={null}
await build({
  root: './my-project',
  logLevel: 'info',
  site: 'https://example.com',
  outDir: './custom-dist',
});
```

## Common Options

These options are available for all API functions:

<ParamField path="root" type="string" default="process.cwd()">
  The root directory of your Astro project. Can be an absolute path or relative to the current working directory.
</ParamField>

<ParamField path="logLevel" type="'debug' | 'info' | 'warn' | 'error' | 'silent'" default="'info'">
  The logging level for Astro's output.
</ParamField>

<ParamField path="mode" type="string" default="'production'">
  The mode to run Astro in. This affects environment variable loading and other build-time behavior.
</ParamField>

<ParamField path="site" type="string">
  Your deployed site URL. Used for generating sitemaps and canonical URLs.
</ParamField>

<ParamField path="base" type="string" default="'/'">
  The base path where your site is deployed.
</ParamField>

<ParamField path="outDir" type="string" default="'./dist'">
  The directory where build output is written.
</ParamField>

<ParamField path="force" type="boolean" default="false">
  Force a clean build by clearing the content layer cache.
</ParamField>

## Use Cases

### Build Tools

Use the JavaScript API to integrate Astro into your existing build pipeline:

```javascript theme={null}
import { build } from 'astro';

async function buildSite() {
  try {
    await build({
      root: './src',
      logLevel: 'info',
    });
    console.log('Build complete!');
  } catch (error) {
    console.error('Build failed:', error);
    process.exit(1);
  }
}

buildSite();
```

### Testing

Start a dev server for integration tests:

```javascript theme={null}
import { dev } from 'astro';

let server;

before(async () => {
  server = await dev({
    root: './test-site',
    logLevel: 'silent',
  });
});

after(async () => {
  await server.stop();
});
```

### Custom Integrations

Build custom tooling that leverages Astro's type generation:

```javascript theme={null}
import { sync } from 'astro';

await sync({
  root: './my-project',
  logLevel: 'info',
});

console.log('TypeScript types generated!');
```

## Next Steps

Explore the individual API function references for detailed parameter information and examples:

* [build()](/api/build) - Production builds
* [dev()](/api/dev) - Development server
* [preview()](/api/preview) - Preview server
* [sync()](/api/sync) - Type generation