Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Integrations with Frameworks

Adding Integrations to an Astro Project

Use astro add to install integrations, read what they change in astro.config, find official ones and write a small custom integration with hooks.

Astro itself is small on purpose. Almost everything else (UI frameworks, Tailwind, MDX, sitemaps, deployment adapters) arrives as an integration: a package that plugs into Astro's build through a defined set of hooks. Once you understand the model, adding any feature looks the same, and writing your own is surprisingly short.

The astro add command

Terminal
npx astro add react
npx astro add mdx sitemap

astro add does three things: installs the package(s) with your package manager, edits astro.config.mjs to register them, and, for some, updates tsconfig.json. It asks before changing anything. You can always do the same by hand.

After npx astro add react sitemap your config looks like this:

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

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

Each integration is a function call returning an integration object. Options go inside the parentheses: react({ include: ['**/react/*'] }).

site is required by @astrojs/sitemap (and useful for canonical URLs and RSS). Without it the build warns and skips the sitemap.

Official integrations

Maintained by the Astro team and published under @astrojs/:

Group Packages
UI frameworks react, preact, vue, svelte, solid-js, alpinejs
Content mdx, markdoc, rss, sitemap
Adapters node, netlify, vercel, cloudflare
Other partytown (move third-party scripts off the main thread), db (Astro DB)

Community integrations cover analytics, icons, CMS clients, PWA support and more. Search the integrations directory on the Astro site, and check that a package is recently updated and supports your Astro major version.

What integrations can do

An integration is an object with a name and a hooks map. The most used hooks:

Hook When Typical use
astro:config:setup Before config is final Add Vite plugins, renderers, scripts, update config, add routes
astro:config:done After config is resolved Read the final config
astro:server:setup Dev server starts Add dev middleware
astro:build:start Build begins Prepare files
astro:build:done Build finished Post-process dist, generate files

Inside astro:config:setup you receive helpers such as updateConfig, injectScript, injectRoute, addMiddleware, addWatchFile and logger.

Writing a tiny integration

Say you want a version.txt in every build with the package version and build time:

JavaScript
// integrations/build-info.mjs
import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

export default function buildInfo({ label = 'site' } = {}) {
  return {
    name: 'build-info',
    hooks: {
      'astro:config:setup': ({ logger }) => {
        logger.info('build-info enabled');
      },
      'astro:build:done': async ({ dir, logger }) => {
        const file = new URL('./version.txt', dir);
        await writeFile(file, `${label} built ${new Date().toISOString()}\n`);
        logger.info(`wrote ${fileURLToPath(file)}`);
      },
    },
  };
}
JavaScript
// astro.config.mjs
import buildInfo from './integrations/build-info.mjs';

export default defineConfig({
  integrations: [buildInfo({ label: 'my-blog' })],
});

Key ideas: the default export is a factory so users can pass options; the object has a name; hooks are optional and async-friendly.

Injecting a script

Integrations often add client code. injectScript takes a stage:

JavaScript
'astro:config:setup': ({ injectScript }) => {
  injectScript('page', `console.log('Hello from an integration');`);
}

Stages: before-hydration, head-inline, page (loaded like a normal module on every page) and page-ssr (runs on the server for every page).

Configuration beyond integrations

Some features are plain config, not integrations:

  • markdown: { shikiConfig, remarkPlugins, rehypePlugins } for Markdown processing.
  • vite: { ... } for any Vite option or plugin.
  • redirects: { '/old': '/new' } for redirects.
  • prefetch, image, build, server, i18n, env.

If a library ships a Vite plugin (like Tailwind v4), you can add it under vite.plugins without an integration wrapper.

Troubleshooting

  • "Integration not working": confirm it is in the integrations array and is called (react(), not react).
  • Version mismatch errors: official packages must match your Astro major version; update together with npx @astrojs/upgrade.
  • Two renderers, one file: with more than one JSX framework you must give each an include pattern (see the next lesson).

Try it: a hook runner

The real Astro loads integrations in order and calls the same hook on each one. This stand-in is a minimal version, so you can see how ordering and config updates work.

JS Integration hooks

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: validate options

Good integrations validate options early. This is the pattern with a plain function.

JS Validate integration options

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does npx astro add react do?

    astro add installs dependencies, edits the config (and sometimes tsconfig) after asking for confirmation.
  2. 2. Why is the integration written react() rather than react?

    Each integration package exports a function so you can pass options and get a fresh integration object.
  3. 3. Which hook is the best place to add a Vite plugin?

    astro:config:setup runs before the config is final and provides updateConfig, so it can add Vite plugins and renderers.
  4. 4. Which package is required for a sitemap to be generated correctly?

    @astrojs/sitemap needs the absolute site URL to write full links.

Summary

  • Integrations extend Astro through hooks; astro add installs and registers them.
  • Official packages cover frameworks, content, adapters and utilities.
  • A custom integration is a function returning { name, hooks }.
  • Plain config options (markdown, vite, redirects) cover many needs without an integration.

Next: React, Vue and Svelte in Astro