LLM Best Practices

Astro: Integrations

3 min read

View markdown source

Overview

Astro integrations extend the build pipeline: they add framework support, Vite plugins, renderers, adapters, and build-time transforms. The astro add CLI command installs an integration, adds the npm package, and patches astro.config.mjs in one step. Use it instead of manual installation; manual edits frequently get the integration order wrong, which causes silent failures.

Use astro add for all official integrations

Run astro add <name> from the project root. Astro prompts before writing to any file.

npx astro add tailwind
npx astro add mdx
npx astro add sitemap
npx astro add react

The command installs the package, writes the import into astro.config.mjs, and (for framework integrations) installs any required peer dependencies. For Tailwind v4, use astro add tailwind; it configures the Vite plugin correctly.

Integration order matters for adapters and renderers

Astro processes integrations in array order. The SSR adapter must come last. Framework renderers (React, Vue, Svelte) must come before any integration that depends on them.

// astro.config.mjs
import { defineConfig } from "astro/config";
import tailwind from "@astrojs/tailwind";
import mdx from "@astrojs/mdx";
import react from "@astrojs/react";
import vercel from "@astrojs/vercel/serverless";
 
export default defineConfig({
  integrations: [
    tailwind(),   // CSS layer, first
    react(),      // framework renderer
    mdx(),        // content transform, after react
    sitemap(),    // build output, before adapter
  ],
  adapter: vercel(),
});

If a page using React inside MDX renders blank, verify that react() comes before mdx() in the array.

Install these integrations on every new project

For a content-heavy site, install these on day one:

  • @astrojs/sitemap: generates /sitemap-index.xml at build time. Zero config required; it discovers pages from the build output.
  • @astrojs/mdx: needed for any content that embeds components. See astro-mdx.
  • @astrojs/tailwind (or Tailwind v4’s Vite plugin directly): CSS utility layer. See tailwind.
  • @astrojs/check: type-checks .astro files in CI. Add it to dev dependencies and run astro check in the CI pipeline.

Add @astrojs/image (now built into astro:assets) only if you need remote image optimization beyond what the built-in <Image /> component provides. See astro-image-optimization.

Use Partytown for third-party scripts

@astrojs/partytown offloads third-party scripts (analytics, tag managers, chat widgets) to a Web Worker, keeping them off the main thread. It integrates with the <script type="text/partytown"> attribute.

npx astro add partytown
<script type="text/partytown" src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXX"></script>

Not all third-party scripts are compatible with Partytown; scripts that write to the DOM synchronously will not work. Test each script in dev before shipping.

Write a custom integration for build-time automation

A custom integration is a plain object with an astro:build:done hook (or another lifecycle hook) and a name property. Use one for generating /llms.txt, writing a search index, or running a custom validation step after build.

// astro.config.mjs
function myPlugin() {
  return {
    name: "my-plugin",
    hooks: {
      "astro:build:done": async ({ pages }) => {
        // write search-index.json, etc.
      },
    },
  };
}
 
export default defineConfig({
  integrations: [myPlugin()],
});

Keep custom integrations small and single-purpose. If the logic grows past 50 lines, move it to its own file and import it.

Verify community integrations before adding them

Community integrations are not reviewed by the Astro team. Before adding one, check the npm download count, the last publish date, and whether it has open issues for the current Astro version. Prefer integrations with Astro 5 in their test matrix.

Run astro check after adding any integration to catch TypeScript errors introduced by the new plugin.

Graph View

Backlinks