Astro Integration Pattern

Astro Integration Pattern

Build or consume Astro integrations to extend the build pipeline — add renderers, inject routes, modify Vite config, and hook into build lifecycle events.

When to Use

• You are adding an official Astro integration (@astrojs/react, @astrojs/tailwind, @astrojs/sitemap) to a project
• You are writing a custom integration to encapsulate shared configuration across multiple Astro projects
• You need to inject a virtual route, a client-side script, or an additional Vite plugin
• You are authoring a third-party integration for the Astro ecosystem
• You want to understand what an integration's hooks are doing to debug build issues

Instructions

1. Add official integrations in astro.config.mjs using the integrations array. Call each integration as a function:

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

export default defineConfig({
  site: 'https://example.com',
  integrations: [react(), tailwind({ applyBaseStyles: false }), sitemap()],
});

2. Create a custom integration as a plain function that returns an object with a name and hooks:

// my-integration.ts
import type { AstroIntegration } from 'astro';

export function myIntegration(options: { debug?: boolean } = {}): AstroIntegration {
  return {
    name: 'my-integration',
    hooks: {
      'astro:config:setup': ({ updateConfig, injectRoute, injectScript, addWatchFile, logger }) => {
        // Modify Vite config
        updateConfig({
          vite: {
            plugins: [myVitePlugin()],
            define: { __DEBUG__: options.debug ?? false },
          },
        });

        // Inject a virtual route
        injectRoute({
          pattern: '/my-integration-page',
          entrypoint: './src/my-integration/page.astro',
        });

        // Inject a script on every page
        injectScript('page', `console.log('Integration active');`);

        logger.info('My integration configured');
      },

      'astro:build:done': ({ dir, routes, logger }) => {
        logger.info(`Build complete. ${routes.length} routes generated.`);
      },
    },
  };
}

3. Use the correct hook for each type of work:

4. Add a custom renderer (for a new UI framework) with addRenderer() inside astro:config:setup:

'astro:config:setup': ({ addRenderer }) => {
  addRenderer({
    name: 'my-framework',
    serverEntrypoint: 'my-framework/server.js',
    clientEntrypoint: 'my-framework/client.js',
    jsxImportSource: 'my-framework',
    jsxTransformOptions: async () => ({
      plugins: [['@babel/plugin-transform-react-jsx', { runtime: 'automatic' }]],
    }),
  });
}

5. Use addWatchFile() to trigger HMR when config files outside the project root change:

'astro:config:setup': ({ addWatchFile, config }) => {
  addWatchFile(new URL('./my-config.json', config.root));
}

6. Read the user's final resolved Astro config in astro:config:done — this is after all integrations have run and the config is finalized:

'astro:config:done': ({ config }) => {
  if (config.output === 'static') {
    // perform SSG-specific setup
  }
}

7. Export your integration alongside defineConfig in astro.config.mjs for colocation, or publish it as a separate npm package following the astro-* naming convention.

Details

Astro integrations are the official extensibility mechanism. They are synchronous or async functions that hook into well-defined lifecycle points in the Astro build pipeline. Unlike Vite plugins (which are lower-level), Astro integrations have access to Astro-specific primitives like injectRoute, addRenderer, and the Astro config object.

Integration execution order:

Integrations are executed in the order they appear in the integrations array. Hook calls within each lifecycle event are also ordered. This matters when integrations modify shared config (e.g., Vite plugins) — later integrations see the changes made by earlier ones.

updateConfig merging:

updateConfig() does a deep merge with the existing config. Call it multiple times if needed — each call merges on top of the previous state. Be careful with arrays (like vite.plugins) — they are concatenated, not replaced.

injectRoute and virtual modules:

injectRoute adds a route to the Astro router backed by an actual file. For truly virtual content (generated at build time), pair it with a Vite virtual module plugin to serve the file from memory.

Integration API stability:

The astro:config:setup and astro:build:done hooks are stable. Hooks prefixed with astro:server:* are available only in development. The full hooks API is documented in the Astro Integrations Reference.

Official integration patterns to study:

• @astrojs/sitemap — minimal integration that generates files in astro:build:done
• @astrojs/tailwind — adds a Vite plugin via updateConfig
• @astrojs/react — uses addRenderer plus updateConfig for JSX transform

Publishing guidelines:

Name your package astro-<feature>. Add astro and astro-component to keywords in package.json. Export the integration as the default export. Add "astro" to peerDependencies.

Source

https://docs.astro.build/en/reference/integrations-reference

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.