feat: add Astro support to PostHog Wizard

[AbdallahAHO]

Deployment.mp4

Summary

This PR adds complete Astro framework support to the PostHog wizard, enabling developers to seamlessly integrate PostHog analytics into their Astro projects with AI-powered setup. The implementation follows PostHog's established patterns while optimizing specifically for Astro's architecture with an inline script approach.

What's Added

Core Features

• Framework Detection: Automatic detection of Astro projects via astro package in package.json
• AI-Powered Setup: Intelligent code generation using LLM to modify existing Astro projects
• Optimized Integration: Inline PostHog script approach eliminating package dependencies
• Complete Wizard Workflow: Full integration including component creation, layout setup, and configuration

New Files

• src/astro/astro-wizard.ts - Main Astro wizard implementation
• src/astro/docs.ts - Astro-specific documentation with dynamic variable injection
• src/utils/rules/astro-rules.md - AI coding rules for Astro projects
• e2e-tests/test-applications/astro-test-app/ - Complete Astro test application
• e2e-tests/tests/astro.test.ts - E2E test suite for Astro integration

Modified Files

• src/lib/constants.ts - Added Astro to Integration enum and descriptions
• src/lib/config.ts - Added Astro detection logic and optimized success messages
• src/run.ts - Added Astro wizard import and routing
• bin.ts - Added 'astro' to CLI integration choices
• README.md - Updated to include Astro integration documentation

Implementation Approach

Astro-Optimized Architecture (following PostHog Astro docs)

1. Inline Script Integration

Unlike other frameworks that rely on npm packages, Astro uses PostHog's inline script approach:

<!-- src/components/posthog.astro -->
<script is:inline type="text/javascript" id="posthog-js">
  !(function(t, e) {
    // Full PostHog loader script embedded directly
    // ... PostHog initialization code ...
  })(document, window.posthog || []);
  posthog.init('actual_api_key_here', { 
    api_host: 'actual_api_host_here' 
  });
</script>

Benefits:

• No package dependencies
• No environment variables needed
• Zero configuration after setup
• Smaller bundle size
• Immediate functionality

2. Component-Based Architecture

Creates reusable Astro components following framework best practices:

PostHog Component (src/components/posthog.astro):

• Self-contained PostHog initialization
• Uses is:inline directive to prevent Astro processing
• Direct API key injection

Layout System (src/layouts/PostHogLayout.astro):

• Consistent analytics across all pages
• Automatic PostHog component inclusion
• Follows Astro layout patterns

Architecture Consistency

Follows PostHog wizard patterns:

1. Detection Logic: Uses hasPackageInstalled('astro', packageJson) to auto-pick framework
2. Wizard Structure: Implements standard step-by-step workflow
3. AI Integration: Uses LLM prompts for intelligent code modification
4. Step System: Integrates with existing steps (rules, MCP setup) - Didn't test them enough though but should work out of the box

Usage

Users can now run:

# Automatic detection
npx @posthog/wizard

# Explicit Astro selection
npx @posthog/wizard --integration=astro

The wizard will:

1. ✅ Create PostHog component with embedded script and actual API keys
2. ✅ Set up layout system for consistent tracking
3. ✅ Add AI coding rules for future development
4. ✅ Set up MCP server integration

What's NOT needed:

• ❌ Package installation (posthog-js)
• ❌ Environment variable configuration
• ❌ Build configuration changes

Testing

E2E Testing

Created comprehensive test suite following existing patterns:

• checkPackageJson() - Verifies no unnecessary package installations
• checkIfRunsOnDevMode() - Tests development server
• checkIfBuilds() - Verifies build process
• checkIfRunsOnProdMode() - Tests preview mode

Test Application

• Uses official create-astro minimal template
• Includes TypeScript support
• Follows standard Astro project structure
• Builds and runs successfully without configuration

Manual Testing ✅

• Framework detection works correctly
• CLI integration choices include Astro
• Wizard launches and completes successfully
• Generated components work immediately
• No environment variable setup required
• PostHog tracking functional out of the box

User Experience

• Zero Configuration: Works immediately after wizard completion
• Faster Setup: No package installation or environment variable management
• Fewer Dependencies: No additional npm packages required
• Deployment Ready: No hosting provider environment variable setup needed

Breaking Changes

None. This is a pure addition that doesn't affect existing functionality.

Code Quality

• All linting rules pass (pnpm lint)
• TypeScript compilation successful (pnpm build)
• All existing tests continue to pass (pnpm test)
• Follows existing code patterns and conventions
• Comprehensive E2E test coverage

---

Checklist

• Added new Astro framework support following PostHog Wizard patterns
• Implemented optimized inline script approach
• Created comprehensive documentation with dynamic variable injection
• Built complete E2E test suite with test application
• Updated CLI and configuration files
• Verified all existing functionality remains intact
• Tested framework detection and wizard execution
• Optimized for Astro-specific architecture and best practices as defined in PostHog docs
• Updated README with Astro integration information

[codecov-commenter]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[daniloc]

This is great, thank you so much for taking the time to do this.

just a couple of tweaks if you could:

• in the initializer, set the defaults argument as in defaults: '2025-05-24'. It's helpful when the wizard implementations closely match the up-to-date docs so people can check the robot's work. We started using that argument recently.
• instead of committing an already-integrated astro app in e2e-tests/test-applications, could you instead include a bare one? Makes it easier to check later that everything works as it should

[AbdallahAHO]

Hey @daniloc,

Thanks for the review. Addressed both points with 2eb5868 and aa909b4 and rebased to latest main

Let me know if there's any other feedback.

[daniloc]

Looks great!

[daniloc]

Thanks again for the help here!