Skip to main content

​
Overview

The Astro configuration file (astro.config.mjs) defines core settings for the Jowy Portfolio application, including site URL, development server options, integrations, and build configuration.

​
Configuration File

The complete configuration is located at the project root: 
// @ts-check
import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";
import sitemap from "@astrojs/sitemap";
import compress from "astro-compress";
import { defaultLang, locales } from "./i18n.config";

// https://astro.build/config
export default defineConfig({
  site: "https://jowy-portfolio.vercel.app/", // cambia a tu dominio
  vite: {
    plugins: [tailwindcss()],
  },
  server: {
    host: true, // Establece el host en '0.0.0.0'
    port: 4321,
  },

  integrations: [sitemap(), compress()],

  i18n: {
    defaultLocale: defaultLang,
    locales: locales,
    routing: {
      prefixDefaultLocale: false,
      redirectToDefaultLocale: true,
    },
  },
});

​
Site Configuration

​
site
string
default:"\"https://jowy-portfolio.vercel.app/\""
The production URL of your deployed site. This is used for:
  • Generating absolute URLs in sitemaps
  • Canonical URLs for SEO
  • Social media meta tags
Update this to your actual domain before deploying to production.

​
Example: Update Site URL

export default defineConfig({
  site: "https://your-domain.com/",
  // ... rest of config
});

​
Vite Configuration

​
vite.plugins
Plugin[]
Array of Vite plugins. Jowy Portfolio uses the Tailwind CSS Vite plugin for styling.
vite: {
  plugins: [tailwindcss()],
}
The @tailwindcss/vite plugin integrates Tailwind CSS v4 directly into the Vite build pipeline, providing faster builds and hot module replacement.

​
Adding Vite Plugins

To add additional Vite plugins: 
import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";
import myPlugin from "vite-plugin-example";

export default defineConfig({
  vite: {
    plugins: [
      tailwindcss(),
      myPlugin(),
    ],
  },
});

​
Server Configuration

​
server.host
boolean | string
default:true
When set to true, the dev server listens on 0.0.0.0, making it accessible from other devices on your network. Useful for testing on mobile devices.
​
server.port
number
default:4321
The port number for the development server. Default is 4321.
server: {
  host: true, // Listens on 0.0.0.0
  port: 4321,
}

​
Accessing Dev Server on Network

With host: true, you can access your dev server from other devices: 
Local:    http://localhost:4321
Network:  http://192.168.1.x:4321
The network address will be displayed in your terminal when you start the dev server.

​
Custom Port

To change the development server port: 
server: {
  host: true,
  port: 3000, // Use port 3000 instead
}

​
Integrations

Jowy Portfolio includes two official Astro integrations:
​
integrations
AstroIntegration[]
Array of Astro integrations to enable additional functionality.

​
Sitemap Integration

import sitemap from "@astrojs/sitemap";

export default defineConfig({
  integrations: [sitemap()],
});
Automatically generates a sitemap.xml file for your site based on the site configuration. Benefits:
  • Improves SEO by helping search engines discover all pages
  • Automatically updates when you add/remove pages
  • Respects i18n configuration for multi-language URLs
sitemap({
  filter: (page) => !page.includes('/admin/'),
  customPages: ['https://your-domain.com/external-page'],
  changefreq: 'weekly',
  priority: 0.7,
  lastmod: new Date(),
})

​
Compress Integration

import compress from "astro-compress";

export default defineConfig({
  integrations: [compress()],
});
Compresses HTML, CSS, and JavaScript files during the build process. Benefits:
  • Reduces file sizes for faster page loads
  • Minifies HTML, CSS, and JavaScript
  • Improves Core Web Vitals scores
  • Reduces bandwidth usage
compress({
  CSS: true,
  HTML: true,
  Image: false,
  JavaScript: true,
  SVG: true,
})

​
Adding More Integrations

To add additional integrations:
  1. Install the integration:
npm install @astrojs/integration-name
  1. Import and add to config:
import newIntegration from "@astrojs/integration-name";

export default defineConfig({
  integrations: [
    sitemap(),
    compress(),
    newIntegration(),
  ],
});

​
Internationalization (i18n)

​
i18n
object
Configuration for Astro’s built-in i18n routing support.
import { defaultLang, locales } from "./i18n.config";

export default defineConfig({
  i18n: {
    defaultLocale: defaultLang,     // "es"
    locales: locales,                // ["es", "en"]
    routing: {
      prefixDefaultLocale: false,
      redirectToDefaultLocale: true,
    },
  },
});
The i18n configuration is imported from i18n.config.ts for centralized language management.
For detailed i18n configuration, see the Internationalization guide.

​
TypeScript Configuration

The // @ts-check comment at the top of the file enables TypeScript checking for JavaScript files: 
// @ts-check
import { defineConfig } from "astro/config";
This provides:
  • Type checking for configuration options
  • IntelliSense in compatible editors
  • Catches configuration errors before runtime

​
Build Configuration

Astro’s default build settings are used, which:
  • Outputs to dist/ directory
  • Generates static HTML files
  • Optimizes assets automatically
  • Creates a production-ready build

​
Custom Build Output

To customize the build output directory: 
export default defineConfig({
  outDir: './build',
  // ... rest of config
});

​
Environment-Specific Configuration

You can create different configurations for development and production: 
import { defineConfig } from "astro/config";

const isDev = import.meta.env.DEV;

export default defineConfig({
  site: isDev 
    ? "http://localhost:4321" 
    : "https://jowy-portfolio.vercel.app/",
  // ... rest of config
});

​
Common Configuration Tasks

​
Change Development Port

server: {
  host: true,
  port: 3000, // Change from 4321 to 3000
}

​
Update Production URL

site: "https://your-custom-domain.com/",

​
Disable Compression in Development

import compress from "astro-compress";

const isDev = import.meta.env.DEV;

export default defineConfig({
  integrations: [
    sitemap(),
    ...(isDev ? [] : [compress()]), // Only compress in production
  ],
});

​
Add Base Path for Subdirectory Deployment

export default defineConfig({
  base: '/my-app',
  site: "https://example.com/my-app/",
});

​
Troubleshooting

After modifying astro.config.mjs, always restart your development server for changes to take effect.

​
Dev server won’t start

  • Check for syntax errors in the config file
  • Ensure all imported packages are installed
  • Verify the port isn’t already in use

​
Sitemap not generating

  • Verify the site option is set correctly
  • Ensure the sitemap integration is included
  • Check that pages are being built (not all dynamic)

​
Tailwind styles not applying

  • Verify @tailwindcss/vite is installed
  • Check that the plugin is in the vite.plugins array
  • Ensure your Tailwind configuration file exists

​
i18n routes not working

  • Confirm i18n.config.ts exports match the imports
  • Verify page structure matches locale configuration
  • Check routing options are correct for your use case

Build docs developers (and LLMs) love

Get started for freeTalk to us