Adding Integrations with astro add

Wiring an integration into Astro by hand means installing a package, importing it in your config, calling it inside the integrations array, and sometimes editing tsconfig.json or package.json too. The astro add command collapses all of that into a single step: it installs the dependency, patches astro.config.mjs, and applies any extra configuration the integration needs — all with a diff you approve before anything is written. It keeps your project’s zero-JS-by-default posture intact while making islands trivially easy to add.

What astro add does

When you run astro add <name>, the CLI performs three jobs in order:

Resolves and installs the package using your detected package manager (npm, pnpm, yarn, or bun).
Updates astro.config.mjs — it adds the import statement and inserts the integration call into the integrations array.
Applies side effects — for UI framework integrations it may update tsconfig.json (e.g. JSX settings), and for adapters it sets the correct output mode.

Crucially, Astro shows you the exact file diffs and prompts for confirmation before touching anything. Nothing is modified until you accept.

Basic usage

Pass one or more integration names. Short names are resolved against the official @astrojs/* scope automatically.

# Add a single UI framework integration
npx astro add react

# Add several at once
npx astro add react tailwind sitemap

# Add a deployment adapter
npx astro add vercel

Astro then prints the planned changes and waits for approval:

Output:

✔ Resolving packages...
  Astro will run the following command:
    npm install @astrojs/react react react-dom

✔ Continue? … yes

  astro.config.mjs
  + import react from '@astrojs/react';
  + integrations: [react()],

✔ Continue? … yes
  success  Added the following integration to your project:
  - @astrojs/react

After it finishes, your config is ready to use immediately.

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

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

You can now drop a React island into any page and hydrate it with a client:* directive:

---
// src/pages/index.astro
import Counter from '../components/Counter.jsx';
---
<html lang="en">
  <body>
    <h1>Shipped with zero JS by default</h1>
    <!-- Only this island ships JavaScript -->
    <Counter client:visible />
  </body>
</html>

Useful flags

The command accepts a few flags that change how it runs, which is handy in CI or scripted setups.

Flag	Effect
`--yes`, `-y`	Skip all confirmation prompts and accept every change.
`--no-` (interactive)	Default behavior: review and confirm each diff.
`PACKAGEMANAGER=...`	Astro detects the manager from your lockfile automatically.

# Non-interactive install, ideal for CI or scaffolding scripts
npx astro add tailwind --yes

Tip: Run astro add from a clean git working tree. Because it rewrites astro.config.mjs, an easy git diff afterward lets you review exactly what changed and revert in one command if needed.

What counts as an integration

astro add handles three categories of packages, all of which plug into the same integrations array:

UI frameworks — react, vue, svelte, solid-js, preact, alpinejs, lit. These enable .jsx/.vue/.svelte components as hydratable islands.
Adapters — vercel, netlify, node, cloudflare. These add on-demand rendering and set the appropriate output mode for your deploy target.
Feature integrations — tailwind, sitemap, mdx, partytown, db. These add build steps, middleware, or content tooling.

For adapters specifically, astro add also wires up server output, so you usually don’t need to set output: 'server' yourself:

// astro.config.mjs — after `astro add node`
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({ mode: 'standalone' }),
});

When manual install is still needed

astro add covers the official integrations and any third-party package that follows the convention. For a community integration with a non-standard name, install it yourself and add it to the array:

npm install astro-some-community-integration

import { defineConfig } from 'astro/config';
import community from 'astro-some-community-integration';

export default defineConfig({
  integrations: [community({ enabled: true })],
});

Warning: If astro add can’t parse your astro.config.mjs (for example, heavily dynamic config built from variables), it will fall back to printing the snippet for you to paste in manually instead of failing silently. Keep your config statically analyzable to get the automatic edits.

Best Practices

Prefer astro add <name> over manual installation for official integrations — it keeps imports, tsconfig.json, and output settings in sync automatically.
Commit before running astro add so the generated diff is easy to review and revert.
Batch related integrations in one command (astro add react tailwind) to resolve dependencies together and patch the config once.
Use --yes only in trusted, non-interactive contexts like CI scripts; review diffs interactively during local development.
Let Astro detect your package manager from the lockfile rather than mixing managers in one project.
After adding a UI framework, hydrate islands with the narrowest client:* directive that works (client:visible over client:load) to preserve zero-JS-by-default performance.