LuisLlamas Logo
configuracion-astro

Advanced Astro Configuration

  • 4 min
  • Intermediate

In Astro, configuration is primarily done through the astro.config.mjs file, which is the main configuration file of any Astro project.

Here we can define a lot of parameters, which allow us to adjust build options, the development server, and third-party integrations.

Generally, it’s not a file we need to touch frequently. Only some of the parameters to adapt it to our needs.

So let’s look at the main options we can control in our Astro project.

If you want to delve deeper into Astro, you can explore the official documentation and experiment with different configurations in your projects.

Basic Configuration of astro.config.mjs

The astro.config.mjs file is the entry point for customizing Astro. This file is a JavaScript module that exports a configuration object.

Let’s look at its basic structure:

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Basic Astro configuration
  site: 'https://my-site.com',
  base: '/',
  output: 'static',
  integrations: [],
  vite: {
    // Vite-specific configuration
  },
  server: {
    // Development server configuration
  },
});
Copied!
  • site: Defines the base URL of your site. This is useful for generating absolute URLs on your site.
  • base: Specifies the base path for your project. If your site is hosted in a subdirectory, you can configure it here.
  • output: Defines the output type. It can be static (for static sites) or server (for server-rendered sites).
  • integrations: Here you can add Astro integrations, such as support for React, Vue, Tailwind, etc.
  • vite: Allows customization of Vite’s configuration.
  • server: Configures Astro’s development server.

Integrations

Astro has a large ecosystem of integrations (plugins) that we can add to our project. For example, if you want to use Tailwind CSS, you can add the corresponding plugin:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [tailwind()],
});
Copied!

You must first install the plugin; here we are only seeing how to add the integration to the configuration. (consult the corresponding plugin’s documentation for more info)

Development Server Configuration

Astro’s development server is configured through the server field in astro.config.mjs. Here you can customize the port, host, and other server-related options.

Let’s see it with some examples.

By default, Astro starts the development server at http://localhost:4321. If we need to change the port or host, we can do it like this:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  server: {
    port: 4000, // Change port to 4000
    host: '0.0.0.0', // Allow connections from any IP
  },
});
Copied!

If you need to redirect certain routes to a backend server, you can configure a proxy:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:5000',
        changeOrigin: true,
      },
    },
  },
});
Copied!

Advanced Vite Configuration in Astro

Under the hood, Astro uses Vite as the build engine. Vite is a great tool, with many options in itself.

We have access to these options through the vite field in the astro.config.mjs file.


export default defineConfig({
  vite: {
    // Vite options
  },
});
Copied!

Let’s also see it with an example,

Path aliases are useful for simplifying imports in your project. For example, instead of writing import Component from '../../../components/Component', you can use an alias like @components.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import path from 'path';

export default defineConfig({
  vite: {
    resolve: {
      alias: {
        '@components': path.resolve(__dirname, 'src/components'),
        '@assets': path.resolve(__dirname, 'src/assets'),
      },
    },
  },
});
Copied!

On this page