add-integration

Add Astro Integration

Use this skill when adding official or community integrations to an Astro project, including UI frameworks, styling tools, adapters, content tooling, and utilities.

If astro-best-practices is available, apply it alongside this skill for performance, accessibility, and hydration defaults.

Workflow

1. Classify the integration

Identify what is being added before changing anything:

• UI framework: React, Vue, Svelte, Preact, Solid
• Styling: Tailwind, UnoCSS, Sass, CSS tooling
• Deployment adapter: Netlify, Vercel, Cloudflare, Node
• Content tooling: MDX, Markdoc, CMS integrations
• Utilities: sitemap, Partytown, analytics, database helpers

This determines whether the change affects rendering mode, hydration, config shape, or build output.

2. Prefer the official Astro path

Use astro add when an official integration supports it:

npx astro add react
npx astro add tailwind
npx astro add netlify

If the integration is community-maintained, install it with the project package manager and wire it into astro.config.* manually.

Before finalizing, verify the current setup in the official Astro docs or the integration README, especially when Astro or the integration recently changed versions.

If the project is also upgrading Astro itself, upgrade Astro and official integrations together. For Astro 6, confirm the environment is running Node 22.12.0 or newer before treating integration issues as application bugs.

3. Configure Astro deliberately

When editing astro.config.*:

• add integrations explicitly and keep the array readable
• set output only when the adapter or runtime requires it
• avoid enabling server output unless the feature actually needs request-time work
• preserve existing config ordering unless the integration docs require a specific sequence

Example:

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

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