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:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

The defineConfig() helper provides TypeScript types and autocomplete in your editor, even if you’re not using TypeScript.

TypeScript Configuration

You can also use TypeScript for your config file:

astro.config.ts

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

We recommend using the .mjs extension to ensure your config is treated as an ES module.

Custom Configuration Path

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

astro dev --config my-config.mjs

Common Configuration Examples

Static Site (Default)

By default, Astro builds a fully static site:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Server-Side Rendering (SSR)

Enable SSR with an adapter:

astro.config.mjs

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:

astro.config.mjs

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:

astro.config.mjs

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:

Top-Level Options

Core settings like site, base, output, and adapter

Build Options

Control build output format, directories, and optimization

Server Options

Configure the dev server port, host, and headers

Integrations

Add framework support, content processing, and more

Environment-Based Configuration

You can conditionally configure Astro based on the environment:

astro.config.mjs

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

The config function receives an object with command (“dev” | “build” | “preview”) and mode properties.

Loading Environment Variables

You can load environment variables in your config:

astro.config.mjs

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

Astro Config Reference

Explore all available configuration options

TypeScript Configuration

Set up TypeScript in your Astro project

Vite Configuration

Customize Vite settings for advanced use cases

Integrations Guide

Learn about Astro’s integration system