Install and Configure Vercel Web Analytics

[vercel]

Vercel Web Analytics Installation Report

Summary

Successfully installed and configured Vercel Web Analytics for the Firefly Astro blog project following the latest official Vercel documentation.

Changes Made

1. Package Installation

• Added dependency: @astrojs/vercel@^9.0.5 (compatible with Astro 5.x)
• Package installed via pnpm and added to package.json
• Updated pnpm-lock.yaml with new dependencies

2. Configuration

Modified: astro.config.mjs

• Imported Vercel static adapter: import vercel from "@astrojs/vercel/static"
• Added output mode: output: "static"
• Configured adapter with Web Analytics enabled:

  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  })

3. Bug Fix (Bonus)

Modified: src/config/profileConfig.ts

• Fixed pre-existing icon set mismatch that was causing build failures
• Changed fa6-brands to fa7-brands for Bilibili and PayPal icons
• This was necessary to ensure the build completes successfully

4. Code Formatting

Modified: src/config/backgroundWallpaper.ts and src/config/navBarConfig.ts

• Biome linter automatically fixed indentation issues
• No functional changes, only formatting improvements

Implementation Details

Following the official Vercel documentation for Astro (https://vercel.com/docs/frameworks/frontend/astro), I used the recommended approach of configuring Web Analytics through the Vercel adapter rather than manually adding the Analytics component. This approach:

1. Automatic injection: The adapter automatically injects the Web Analytics script (/_vercel/insights/script.js) into all pages
2. Zero configuration: No manual component imports needed in layouts
3. Optimized: Uses Vercel's automatic configuration via build environment variables
4. Production-ready: Analytics are automatically enabled when deployed to Vercel

Verification

✅ Type checking passed: pnpm run check completed with 0 errors
✅ Build successful: pnpm run build completed without issues
✅ Linting passed: pnpm run lint completed and fixed formatting
✅ Analytics script injected: Verified /_vercel/insights/script.js is present in built HTML files

How It Works

When deployed to Vercel:

1. The adapter injects the Web Analytics script into all HTML pages
2. Vercel automatically provides configuration via the VERCEL_OBSERVABILITY_CLIENT_CONFIG environment variable
3. Analytics start collecting page views and events automatically
4. Data is viewable in the Vercel dashboard under Analytics

Next Steps

After deploying to Vercel:

1. Visit your Vercel project dashboard
2. Navigate to the "Analytics" tab
3. If not already enabled, click "Enable Web Analytics"
4. Analytics data will start appearing after users visit your site
5. Verify in browser DevTools that requests to /_vercel/insights/view are being made

Notes

• Used @astrojs/vercel@^9.0.5 for compatibility with Astro 5.17.3 (version 10.x requires Astro 6)
• The adapter uses the /static variant as this is a static site build
• Web Analytics are free and don't require any additional Vercel configuration
• The implementation follows Vercel's official best practices for Astro projects

---

View Project · Web Analytics

Created by xlhxzkill-7147 with Vercel Agent

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
firefly-blog	Ready	Preview, Comment	Mar 20, 2026 4:49pm