name: component-integration
description: React, MDX, and Tailwind CSS integration patterns for Astro websites. Use when adding React components, configuring MDX content, setting up Tailwind styling, integrating component libraries, building interactive UI elements, or when user mentions React integration, MDX setup, Tailwind configuration, component patterns, or UI frameworks.
allowed-tools: - Read
- Write
- Edit
- Bash
- Glob
- Grep
Component Integration
Comprehensive patterns for integrating React components, MDX content, and Tailwind CSS into Astro websites with type safety, performance optimization, and best practices.
Overview
This skill provides:
- React component integration with Astro islands architecture
- MDX configuration for content-rich component authoring
- Tailwind CSS setup with custom design systems
- Type-safe component patterns with TypeScript
- Performance optimization techniques
- Component library integration (shadcn/ui, Radix, etc.)
Setup Scripts
Core Setup Scripts
- scripts/setup-react.sh - Initialize React integration in Astro project
- scripts/setup-mdx.sh - Configure MDX support with plugins
- scripts/setup-tailwind.sh - Install and configure Tailwind CSS
- scripts/validate-integration.sh - Validate component integration setup
- scripts/optimize-components.sh - Apply performance optimizations
Utility Scripts
- scripts/generate-component.sh - Scaffold new React components
- scripts/add-component-library.sh - Integrate shadcn/ui or other libraries
Templates
React Component Templates
- templates/react/basic-component.tsx - Simple React component with TypeScript
- templates/react/interactive-component.tsx - Interactive component with state
- templates/react/island-component.tsx - Astro island with client directives
- templates/react/form-component.tsx - Form component with validation
- templates/react/data-fetching-component.tsx - Component with async data
- templates/react/component-with-context.tsx - Context provider pattern
MDX Templates
- templates/mdx/basic-mdx.mdx - Basic MDX file structure
- templates/mdx/mdx-with-components.mdx - MDX using custom components
- templates/mdx/mdx-layout.astro - Layout wrapper for MDX content
- templates/mdx/remark-plugin.js - Custom remark plugin template
Tailwind Templates
- templates/tailwind/tailwind.config.ts - Full Tailwind configuration
- templates/tailwind/custom-theme.ts - Custom design system theme
- templates/tailwind/base-styles.css - Base CSS with custom utilities
- templates/tailwind/component-variants.ts - CVA variant patterns
Integration Templates
- templates/integration/astro-config-full.ts - Complete Astro config
- templates/integration/tsconfig-components.json - TypeScript config for components
- templates/integration/package-json-deps.json - Required dependencies
Examples
- examples/basic-integration.md - Simple React component in Astro
- examples/mdx-blog-post.md - MDX blog post with components
- examples/tailwind-design-system.md - Custom Tailwind design system
- examples/interactive-forms.md - Forms with validation and state
- examples/component-library-integration.md - shadcn/ui setup guide
- examples/performance-optimization.md - Islands architecture best practices
- examples/type-safe-patterns.md - TypeScript patterns for components
Instructions
Phase 1: Initial Setup
-
Assess Current Setup
# Check existing integrations
bash scripts/validate-integration.sh
-
Install Required Integrations
# Setup React
bash scripts/setup-react.sh
# Setup MDX
bash scripts/setup-mdx.sh
# Setup Tailwind
bash scripts/setup-tailwind.sh
-
Validate Installation
- Check astro.config.mjs for integrations
- Verify package.json dependencies
- Test basic component rendering
Phase 2: Component Development
-
Generate Component Structure
# Create new component
bash scripts/generate-component.sh ComponentName --type interactive
-
Apply Templates
- Use templates/react/* for React components
- Use templates/mdx/* for content components
- Use templates/tailwind/* for styling patterns
-
Implement Type Safety
- Define component props interfaces
- Use TypeScript strict mode
- Export component types for consumers
Phase 3: Styling Integration
-
Configure Tailwind Theme
- Read: templates/tailwind/tailwind.config.ts
- Customize colors, fonts, spacing
- Add custom utilities and variants
-
Create Component Variants
- Use CVA (class-variance-authority) pattern
- Read: templates/tailwind/component-variants.ts
- Define size, color, and style variants
-
Setup Base Styles
- Read: templates/tailwind/base-styles.css
- Add custom CSS variables
- Define global typography styles
Phase 4: MDX Configuration
-
Setup MDX Processing
- Configure remark and rehype plugins
- Read: templates/mdx/remark-plugin.js
- Add syntax highlighting, image optimization
-
Create MDX Layouts
- Read: templates/mdx/mdx-layout.astro
- Design consistent content layouts
- Add frontmatter-based customization
-
Register Custom Components
- Map components to MDX elements
- Read: templates/mdx/mdx-with-components.mdx
- Enable rich content authoring
Phase 5: Performance Optimization
-
Apply Islands Architecture
- Use client:* directives strategically
- Read: examples/performance-optimization.md
- Minimize client JavaScript
-
Optimize Component Loading
bash scripts/optimize-components.sh
-
Implement Code Splitting
- Use dynamic imports for heavy components
- Lazy load below-the-fold content
- Defer non-critical interactions
Phase 6: Component Library Integration
-
Add Component Libraries
# Add shadcn/ui
bash scripts/add-component-library.sh shadcn-ui
-
Configure Library Theming
- Integrate library tokens with Tailwind
- Customize component defaults
- Ensure consistent design language
-
Create Wrapper Components
- Wrap library components for Astro compatibility
- Add project-specific defaults
- Maintain type safety
Best Practices
React Integration
- Use Islands Architecture: Only hydrate interactive components
- Minimize Bundle Size: Import only needed components
- Type Everything: Use TypeScript interfaces for all props
- Avoid Layout Shift: Reserve space for hydrated components
- Handle SSR: Ensure components work server-side
MDX Content
- Separate Content from Logic: Keep MDX focused on content
- Use Frontmatter: Add metadata for routing and SEO
- Component Consistency: Reuse components across MDX files
- Optimize Images: Use Astro Image optimization
- Test Rendering: Validate MDX compiles correctly
Tailwind Styling
- Design Tokens: Define colors, spacing in config
- Utility Classes: Prefer utilities over custom CSS
- Component Variants: Use CVA for variant management
- Responsive Design: Mobile-first approach
- Dark Mode: Configure dark mode variant strategy
Performance
- Static First: Generate static HTML by default
- Selective Hydration: Use client:visible, client:idle
- Bundle Analysis: Monitor JavaScript bundle sizes
- CSS Optimization: Purge unused Tailwind classes
- Image Optimization: Use Astro Image component
Common Patterns
Pattern 1: Interactive Island Component
// Component with selective hydration
import { useState } from 'react';
interface Props {
initialCount?: number;
}
export default function Counter({ initialCount = 0 }: Props) {
const [count, setCount] = useState(initialCount);
return (
<button onClick={() => setCount(count + 1)}>
Count: {count}
</button>
);
}
Usage in Astro:
---
import Counter from '@/components/Counter';
---
<Counter client:visible initialCount={5} />
Pattern 2: MDX with Custom Components
---
title: "Blog Post with Components"
---
import { Alert } from '@/components/Alert';
# My Blog Post
<Alert type="info">
This is custom component in MDX
</Alert>
Pattern 3: Tailwind Variant Component
import { cva, type VariantProps } from 'class-variance-authority';
const buttonVariants = cva(
'rounded-md font-medium transition-colors'
{
variants: {
variant: {
primary: 'bg-blue-600 text-white hover:bg-blue-700'
secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300'
}
size: {
sm: 'px-3 py-1.5 text-sm'
md: 'px-4 py-2 text-base'
lg: 'px-6 py-3 text-lg'
}
}
defaultVariants: {
variant: 'primary'
size: 'md'
}
}
);
type ButtonProps = VariantProps<typeof buttonVariants> & {
children: React.ReactNode;
};
export function Button({ variant, size, children }: ButtonProps) {
return (
<button className={buttonVariants({ variant, size })}>
{children}
</button>
);
}
Troubleshooting
React Components Not Hydrating
Problem: Components render statically but don't have interactivity
Solution:
- Add client directive:
client:load, client:visible, or client:idle
- Ensure component is exported as default
- Check for SSR-incompatible code (window, document)
MDX Compilation Errors
Problem: MDX files fail to compile
Solution:
- Validate MDX syntax (closing tags, component imports)
- Check remark/rehype plugin compatibility
- Ensure imported components are available
- Review astro.config.mjs MDX configuration
Tailwind Classes Not Applied
Problem: Tailwind utilities not working in components
Solution:
- Check tailwind.config.ts content paths include component files
- Import Tailwind base styles in layout
- Verify PostCSS configuration
- Clear Astro cache:
rm -rf .astro
Type Errors in Components
Problem: TypeScript errors in React components
Solution:
- Review templates/integration/tsconfig-components.json
- Ensure @types/react is installed
- Check jsx compiler options
- Validate component prop interfaces
Related Skills
- content-collections: Use for structured content with type safety
- performance-optimization: Additional performance patterns
- testing-patterns: Testing React components in Astro
Requirements
- Node.js 18+
- Astro 4.0+
- React 18+
- Tailwind CSS 3.4+
- TypeScript 5.0+
Plugin: website-builder
Version: 1.0.0