@astro-kits/google-analytics
v0.1.0
Published
Google Analytics integration for Astro with Partytown
Downloads
279
Maintainers
handystudioReadme
@astro-kits/google-analytics
A performance-optimized Google Analytics integration for Astro that leverages Partytown to run analytics scripts in a web worker.
Features
- 🚀 Web Worker Powered: Offloads Google Analytics to a web worker using Partytown
- 🔄 Simple Integration: Drop-in component for any Astro project
- 🔧 Configurable: Options for development/production behavior
- 📦 Lightweight: Minimal implementation with no unnecessary features
- ⚡ Performance First: Improves main thread performance
- 🔐 Environment Variables: Automatically use GA ID from environment variables
Installation
# npm
npm install @astro-kits/google-analytics @astrojs/partytown
# yarn
yarn add @astro-kits/google-analytics @astrojs/partytown
# pnpm
pnpm add @astro-kits/google-analytics @astrojs/partytownSetup
1. Configure Partytown in your Astro config
// astro.config.mjs
import { defineConfig } from "astro/config";
import partytown from "@astrojs/partytown";
export default defineConfig({
integrations: [
partytown({
config: {
forward: ["dataLayer.push", "gtag"],
},
}),
],
});2. Set up environment variables (optional)
Create a .env file in your project root:
GA_ID=G-XXXXXXXXXX3. Import and use the component
---
// src/layouts/Layout.astro
import GoogleAnalytics from '@astro-kits/google-analytics';
---
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>My Astro Site</title>
<!-- Add Google Analytics -->
<GoogleAnalytics /> <!-- Will use ID from environment variables -->
</head>
<body>
<slot />
</body>
</html>Configuration Options
| Option | Type | Default | Description |
| ------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| id | string | undefined | Your Google Analytics measurement ID (G-XXXXXXXXXX). If not provided, will use GA_ID from environment variables |
| partytown | boolean | true | Whether to use Partytown to run GA in a web worker |
| production | boolean | true | Only load analytics in production environment |
Examples
Basic Usage (with ID from environment variables)
<GoogleAnalytics />Explicitly Providing Measurement ID
<GoogleAnalytics id="G-XXXXXXXXXX" />Without Partytown (run on main thread)
<GoogleAnalytics partytown={false} />Load in Development Environment
<GoogleAnalytics production={false} />How It Works
This component:
- Loads the Google Analytics gtag.js script
- Gets the GA ID from props or falls back to the
GA_IDenvironment variable - Initializes Google Analytics with the provided ID
- Uses Partytown to run the scripts in a web worker (by default)
- Conditionally loads only in production environments (by default)
Component Implementation
The component automatically checks for the Google Analytics ID in this order:
- From the
idprop if provided - From the
GA_IDenvironment variable - Logs a warning if no ID is found
---
// Example of component implementation
export interface Props {
id?: string; // Google Analytics measurement ID (G-XXXXXXXXXX)
partytown?: boolean; // Whether to use Partytown
production?: boolean; // Only load in production environment
}
// Get the Google Analytics ID from the .env file
const GA_ID = import.meta.env.GA_ID;
const {
id = GA_ID,
partytown = true,
production = true
} = Astro.props;
// Component logic...
---Performance Benefits
By running Google Analytics in a web worker:
- Reduces main thread execution time
- Improves page load performance
- Reduces impact on Core Web Vitals
- Better user experience with less main thread blocking
Browser Compatibility
This component is compatible with all modern browsers. Partytown provides fallbacks for browsers that don't support web workers.
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request