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:

astro:config:setup

updateConfig

injectRoute

injectScript

addRenderer

astro:config:done

astro:server:setup

astro:server:start

astro:build:start

astro:build:done

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

Integration execution order:

Integrations are executed in the order they appear in the

integrations

updateConfig

updateConfig()

vite.plugins

injectRoute

injectRoute

Integration API stability:

The

astro:config:setup

astro:build:done

astro:server:*

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>

astro

astro-component

keywords

package.json

"astro"

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.