Skip to main content
This guide covers the configuration options available in your Astro landing page project. You can customize the build process, TypeScript settings, and Astro behavior through configuration files.

​
Astro configuration

The astro.config.mjs file controls how Astro builds and serves your site. This minimal starter uses a basic configuration, but you can extend it with numerous options.

​
Basic configuration

The default configuration uses Astro’s standard settings:
astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});

​
Common configuration options

While the starter template uses default settings, you can customize your project by adding configuration options:
​
site
string
The URL where your site will be deployed. Required for generating sitemaps and canonical URLs.
export default defineConfig({
  site: 'https://example.com'
});
​
base
string
The base path where your site will be deployed. Useful when deploying to a subdirectory.
export default defineConfig({
  base: '/my-app'
});
​
outDir
string
default:"./dist"
The directory where Astro writes your final build output.
export default defineConfig({
  outDir: './build'
});
​
publicDir
string
default:"./public"
The directory for static assets that are served as-is.
export default defineConfig({
  publicDir: './static'
});
​
trailingSlash
string
default:"ignore"
Controls whether route URLs should have trailing slashes. Options: 'always', 'never', or 'ignore'.
export default defineConfig({
  trailingSlash: 'never'
});

​
Server configuration

Configure the development server behavior:
​
server.port
number
default:"4321"
The port to run the development server on.
export default defineConfig({
  server: {
    port: 3000
  }
});
​
server.host
boolean | string
default:"false"
Set which network IP addresses the server should listen on. Set to true to listen on all addresses.
export default defineConfig({
  server: {
    host: true
  }
});

​
Build configuration

Customize the build output:
​
build.format
string
default:"directory"
Controls the file format of each page’s build output. Options: 'file' or 'directory'.
export default defineConfig({
  build: {
    format: 'file'  // Generates about.html instead of about/index.html
  }
});
The minimal starter template uses Astro’s default configuration. You can add any of these options as your project grows.

​
TypeScript configuration

The tsconfig.json file configures TypeScript’s behavior in your project. This starter uses Astro’s strict preset for maximum type safety.

​
Base configuration

tsconfig.json
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

​
Configuration breakdown

​
extends
string
Inherits settings from Astro’s strict TypeScript configuration. This provides recommended TypeScript settings optimized for Astro projects.Available presets:
  • astro/tsconfigs/base - Basic TypeScript support
  • astro/tsconfigs/strict - Strict type checking (recommended)
  • astro/tsconfigs/strictest - Maximum type safety
​
include
array
Specifies which files TypeScript should process:
  • .astro/types.d.ts - Auto-generated type definitions
  • **/* - All files in the project
​
exclude
array
Excludes the dist directory (build output) from TypeScript processing.

​
Customizing TypeScript settings

You can add compiler options to override or extend the base configuration: 
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  }
}
Path aliases defined in tsconfig.json must also be configured in astro.config.mjs using the vite.resolve.alias option for runtime resolution.

​
Environment-specific configuration

You can use environment variables to configure different settings for development and production:
astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: process.env.SITE_URL || 'http://localhost:4321',
  server: {
    port: process.env.PORT ? parseInt(process.env.PORT) : 4321
  }
});
Always validate and sanitize environment variables before using them in your configuration to prevent security issues.

​
Configuration best practices

The astro.config.mjs file includes // @ts-check at the top to enable TypeScript checking in JavaScript files. This catches configuration errors before runtime.
The starter template provides a minimal configuration. Add options only when you need them to keep your configuration maintainable.
Use Astro’s TypeScript presets (strict, strictest) rather than configuring all compiler options manually. This ensures compatibility with Astro’s build system.
If you add non-standard configuration options, document why they’re needed for future maintainers.

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us