> ## 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.

# Configuration Overview

> Learn how to configure your Astro project with astro.config.mjs

Astro is highly configurable through the `astro.config.mjs` file in your project root. This guide covers how to create and structure your Astro configuration file.

## Creating a Configuration File

Astro projects are configured using the `astro.config.mjs` file (or `.ts` for TypeScript). This file is optional - Astro ships with sensible defaults - but you'll likely want to add one as your project grows.

### Basic Configuration

Use the `defineConfig()` helper to get IntelliSense and type-safety in your config:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';

export default defineConfig({
  // Your configuration options here
});
```

<Note>
  The `defineConfig()` helper provides TypeScript types and autocomplete in your editor, even if you're not using TypeScript.
</Note>

### TypeScript Configuration

You can also use TypeScript for your config file:

```ts title="astro.config.ts" theme={null}
import { defineConfig } from 'astro/config';

export default defineConfig({
  // Configuration with full type safety
});
```

## Configuration File Locations

Astro will automatically look for a configuration file in your project root. Supported formats:

* `astro.config.mjs` (recommended)
* `astro.config.js`
* `astro.config.ts`
* `astro.config.mts`

<Tip>
  We recommend using the `.mjs` extension to ensure your config is treated as an ES module.
</Tip>

### Custom Configuration Path

You can specify a custom config file location using the `--config` CLI flag:

```bash theme={null}
astro dev --config my-config.mjs
```

## Common Configuration Examples

### Static Site (Default)

By default, Astro builds a fully static site:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
});
```

### Server-Side Rendering (SSR)

Enable SSR with an adapter:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});
```

### With Framework Integrations

Add framework support with integrations:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import vue from '@astrojs/vue';

export default defineConfig({
  integrations: [react(), vue()],
});
```

### With Content Integrations

Add content processing capabilities:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://example.com',
  integrations: [mdx(), sitemap()],
});
```

## Configuration Categories

Astro's configuration options are organized into several categories:

<CardGroup cols={2}>
  <Card title="Top-Level Options" icon="gear" href="/config/astro-config">
    Core settings like `site`, `base`, `output`, and `adapter`
  </Card>

  <Card title="Build Options" icon="hammer" href="/config/astro-config">
    Control build output format, directories, and optimization
  </Card>

  <Card title="Server Options" icon="server" href="/config/astro-config">
    Configure the dev server port, host, and headers
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/config/astro-config">
    Add framework support, content processing, and more
  </Card>
</CardGroup>

## Environment-Based Configuration

You can conditionally configure Astro based on the environment:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';

export default defineConfig(({ command, mode }) => {
  // command is 'dev' or 'build'
  // mode is the Vite mode (development, production, etc.)
  
  return {
    server: {
      port: command === 'dev' ? 4321 : 4000
    },
  };
});
```

<Info>
  The config function receives an object with `command` ("dev" | "build" | "preview") and `mode` properties.
</Info>

## Loading Environment Variables

You can load environment variables in your config:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';
import { loadEnv } from 'vite';

const { SITE_URL } = loadEnv(process.env.NODE_ENV, process.cwd(), '');

export default defineConfig({
  site: SITE_URL,
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Astro Config Reference" icon="book" href="/config/astro-config">
    Explore all available configuration options
  </Card>

  <Card title="TypeScript Configuration" icon="code" href="/config/typescript">
    Set up TypeScript in your Astro project
  </Card>

  <Card title="Vite Configuration" icon="bolt" href="/config/vite">
    Customize Vite settings for advanced use cases
  </Card>

  <Card title="Integrations Guide" icon="puzzle-piece" href="/integrations/overview">
    Learn about Astro's integration system
  </Card>
</CardGroup>