Add Integration

Add Integration

When to Use

• Adding a UI framework (React, Vue, Svelte, etc.)
• Setting up Tailwind CSS or other styling tools
• Configuring deployment adapters (Netlify, Vercel, Cloudflare)
• Installing community integrations
• Troubleshooting integration issues

Instructions

1. Identify Integration Type

2. Installation

Official integrations (support astro add):

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

Community integrations (manual install):

npm install astro-integration-name

Then add to astro.config.mjs:

import { defineConfig } from 'astro/config'
import integration from 'astro-integration-name'

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

Astro 6 upgrade note

If the project is upgrading Astro itself, do not upgrade integrations in isolation:

1. Verify the environment is running Node 22.12.0 or newer
2. Upgrade Astro and official integrations/adapters together
3. Re-check the official docs before copying older config snippets into the project

This catches a large class of "the integration broke" issues that are actually runtime or version skew problems.

3. Post-Install Configuration

Tailwind CSS v4

After npx astro add tailwind:

1. Create CSS file src/styles/global.css:

   @import "tailwindcss";
   

2. Import in your layout:

   ---
   import '../styles/global.css'
   ---
   

3. Optional: Configure in tailwind.config.mjs for customization

React / Vue / Svelte

After adding a framework, understand client directives:

---
import Counter from './Counter.tsx'
---

<!-- No directive = server-rendered only, no JS -->
<Counter />

<!-- client:load = hydrate immediately (critical interactivity) -->
<Counter client:load />

<!-- client:idle = hydrate when browser is idle -->
<Counter client:idle />

<!-- client:visible = hydrate when scrolled into view -->
<Counter client:visible />

<!-- client:media = hydrate on media query match -->
<Counter client:media="(max-width: 768px)" />

<!-- client:only = skip server render entirely -->
<Counter client:only="react" />

Best practice: Start with client:visible or client:idle, use client:load only for above-the-fold critical UI.

Deployment Adapters

Netlify (npx astro add netlify):

// astro.config.mjs
import { defineConfig } from 'astro/config'
import netlify from '@astrojs/netlify'

export default defineConfig({
  output: 'server', // or 'hybrid'
  adapter: netlify(),
})

Set environment variables in Netlify dashboard or netlify.toml.

Vercel (npx astro add vercel):

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

export default defineConfig({
  output: 'server',
  adapter: vercel({
    webAnalytics: { enabled: true }, // Optional
  }),
})

Cloudflare (npx astro add cloudflare):

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    platformProxy: { enabled: true }, // For local dev
  }),
})

MDX

After npx astro add mdx:

• .mdx files work in src/pages/ and src/content/
• Import components directly in MDX files
• Configure remark/rehype plugins in astro.config.mjs:

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

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkPlugin],
    rehypePlugins: [rehypePlugin],
  },
})

4. Multiple Integrations

Order can matter. General guidelines:

export default defineConfig({
  integrations: [
    // UI frameworks first
    react(),
    vue(),
    // Then styling
    tailwind(),
    // Then content
    mdx(),
    // Then utilities
    sitemap(),
  ],
})

5. Troubleshooting

Finding Integrations

• Official: docs.astro.build/integrations
• Community: astro.build/integrations