Integrations

In Next.js you extend the framework through next.config.js — webpack plugins, Babel transforms, rewrites, redirects, and third-party packages that patch into the build pipeline. Astro has a first-class concept called integrations that covers the same surface area but is more explicit: each integration is an npm package that is registered in astro.config.mjs and can touch the build pipeline, dev server, and output.

`astro.config.mjs` vs `next.config.js`

// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
  images: {
    domains: ['images.unsplash.com'],
  },
  async redirects() {
    return [
      { source: '/old', destination: '/new', permanent: true },
    ];
  },
};

module.exports = withBundleAnalyzer(nextConfig);

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
import sitemap from '@astrojs/sitemap';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    react(),
    tailwind(),
    sitemap(),
  ],
  adapter: vercel(),
  redirects: {
    '/old': '/new',
  },
});

The defineConfig helper gives you full TypeScript autocomplete in your editor. All integrations are listed in the integrations array — there is no wrapping/composing pattern like withBundleAnalyzer(nextConfig).

Adding integrations with `astro add`

# UI framework integrations
npx astro add react          # @astrojs/react — enables .tsx islands
npx astro add preact         # @astrojs/preact — lighter React-compatible alternative
npx astro add svelte         # @astrojs/svelte
npx astro add vue            # @astrojs/vue

# Styling
npx astro add tailwind       # @astrojs/tailwind — auto-injects Tailwind into every page

# Site utilities
npx astro add sitemap        # @astrojs/sitemap — generates sitemap.xml at build
npx astro add mdx            # @astrojs/mdx    — MDX support for content pages

# SSR adapters (pick one)
npx astro add vercel         # @astrojs/vercel
npx astro add netlify        # @astrojs/netlify
npx astro add node           # @astrojs/node (self-hosted Node.js)
npx astro add cloudflare     # @astrojs/cloudflare

Each command installs the package and edits astro.config.mjs for you. You can always edit the config by hand afterwards.

Integration shape

An Astro integration is just a function that returns a config object. Here is what a minimal custom integration looks like:

import { defineConfig } from 'astro/config';

function myPlugin() {
  return {
    name: 'my-plugin',
    hooks: {
      'astro:build:done': ({ dir }) => {
        console.log('Build finished. Output:', dir.pathname);
      },
    },
  };
}

export default defineConfig({
  integrations: [myPlugin()],
});

You will rarely write custom integrations — the official @astrojs/* packages cover the common cases — but understanding the shape helps when you read integration source code.

Passing options to integrations

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

export default defineConfig({
  integrations: [
    react({
      include: ['**/interactive/**'],  // only hydrate components in this dir
    }),
    tailwind({
      applyBaseStyles: false,          // skip Tailwind's base reset
    }),
  ],
});