add-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Astro Integration

添加Astro集成

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

astro-best-practices

is available, apply it alongside this skill for performance, accessibility, and hydration defaults.

当为Astro项目添加官方或社区集成时使用此技能，涵盖UI框架、样式工具、适配器、内容工具及实用程序。

若

astro-best-practices

可用，请结合此技能使用，以遵循性能、可访问性和水化默认规范。

Workflow

工作流程

1. Classify the integration

1. 分类集成类型

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.

在进行任何更改前，先明确要添加的集成类型：

UI框架：React、Vue、Svelte、Preact、Solid
样式工具：Tailwind、UnoCSS、Sass、CSS工具
部署适配器：Netlify、Vercel、Cloudflare、Node
内容工具：MDX、Markdoc、CMS集成
实用程序：站点地图、Partytown、分析工具、数据库辅助工具

这将决定更改是否会影响渲染模式、水化、配置结构或构建输出。

2. Prefer the official Astro path

2. 优先使用Astro官方方式

Use

astro add

when an official integration supports it:

bash

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.

当官方集成支持时，使用

astro add

命令：

bash

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

如果是社区维护的集成，请使用项目包管理器安装，并手动将其配置到

astro.config.*

中。

在完成配置前，请查阅Astro官方文档或集成的README以确认当前设置，尤其是当Astro或集成最近更新版本时。

如果项目同时要升级Astro本身，请将Astro和官方集成一起升级。对于Astro 6版本，在将集成问题视为应用程序bug之前，请确认环境运行的是Node 22.12.0或更高版本。

3. Configure Astro deliberately

3. 谨慎配置Astro

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()],
})

编辑

astro.config.*

时：

显式添加集成，保持数组可读性
仅当适配器或运行时需要时才设置
```
output
```
除非功能确实需要请求时处理，否则避免启用服务器输出
除非集成文档要求特定顺序，否则保留现有配置顺序

示例：

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

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

4. Handle framework components with restraint

4. 克制使用框架组件

When adding React, Vue, or another UI framework:

prefer
```
.astro
```
for static content
keep framework components for interactive islands
choose the lightest client directive that satisfies the UX

Hydration guidance:

```
client:visible
```
for below-the-fold or deferred UI
```
client:idle
```
for non-critical enhancements
```
client:load
```
only for immediately interactive UI
```
client:only
```
only when skipping server rendering is intentional

添加React、Vue或其他UI框架时：

静态内容优先使用
```
.astro
```
组件
框架组件仅用于交互式独立模块（islands）
选择满足用户体验需求的最轻量客户端指令

水化指导：

```
client:visible
```
用于折叠下方或延迟加载的UI
```
client:idle
```
用于非关键增强功能
```
client:load
```
仅用于需立即交互的UI
```
client:only
```
仅在有意跳过服务器渲染时使用

5. Finish the surrounding setup

5. 完成相关配套设置

Do not stop at package installation. Check for:

stylesheet imports or entrypoints
environment variables
config files such as
```
tailwind.config.*
```
adapter-specific output requirements
platform deployment settings

For Tailwind v4, the minimum setup is often just:

css

@import "tailwindcss";

and importing that stylesheet from a shared layout or entrypoint.

不要仅停留在包安装阶段，需检查以下内容：

样式表导入或入口点
环境变量
配置文件如
```
tailwind.config.*
```
适配器特定的输出要求
平台部署设置

对于Tailwind v4，最小化设置通常仅需：

css

@import "tailwindcss";

并从共享布局或入口点导入该样式表。

6. Validate the result

6. 验证结果

After setup:

confirm the integration is registered in
```
astro.config.*
```
run the project checks that make sense for the repo, such as
```
astro check
```
,
```
astro build
```
, or the existing test suite
confirm the deployment/runtime environment still matches the adapter requirements after major Astro upgrades
inspect for hydration mismatches, missing styles, or adapter/runtime drift

设置完成后：

确认集成已在
```
astro.config.*
```
中注册
运行适合仓库的项目检查，如
```
astro check
```
、
```
astro build
```
或现有测试套件
重大Astro升级后，确认部署/运行时环境仍符合适配器要求
检查是否存在水化不匹配、样式缺失或适配器/运行时偏差问题

Common Failure Modes

常见失败模式

Package installed but not added to
```
integrations
```
Adapter added without matching
```
output
```
Styles present but never imported
Framework component added where a plain
```
.astro
```
component would be simpler
Overuse of
```
client:load
```
, increasing JavaScript cost

已安装包但未添加到
```
integrations
```
数组中
添加了适配器但未设置匹配的
```
output
```
存在样式但从未导入
在可以使用普通
```
.astro
```
组件的地方添加了框架组件
过度使用
```
client:load
```
，增加JavaScript加载成本