[![npm](https://img.shields.io/npm/v/@entrolytics/astro-sdk.svg?logo=npm)](https://www.npmjs.com/package/@entrolytics/astro-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Astro](https://img.shields.io/badge/Astro-5+-BC52EE.svg?logo=astro&logoColor=white)](https://astro.build/)

--- ## Overview **@entrolytics/astro-sdk** is the official Astro SDK for Entrolytics - first-party growth analytics for the edge. Add analytics to your Astro sites with a single integration. **Why use this SDK?** - Zero-config Astro integration - just add to `astro.config.mjs` - Automatic View Transitions support - Outbound link and file download tracking - Edge-optimized with sub-50ms response times globally ## Key Features

### Analytics - Automatic page view tracking - Outbound link tracking - File download tracking - Cross-domain tracking

### Developer Experience - Astro integration plugin - Client module for manual tracking - View Transitions aware - Full TypeScript support

## Quick Start

1. Install
npm i @entrolytics/astro-sdk 2. Add Integration
integrations: [entrolytics()] 3. Configure
Set Website ID in .env 4. Track
View analytics in dashboard

## Installation ```bash npm install @entrolytics/astro-sdk # or pnpm add @entrolytics/astro-sdk ``` ```ts // astro.config.mjs import { defineConfig } from "astro/config"; import entrolytics from "@entrolytics/astro-sdk"; export default defineConfig({ integrations: [ entrolytics(), // Zero-config: reads from .env ], }); ``` Add to your `.env` file: ```bash PUBLIC_ENTROLYTICS_WEBSITE_ID=your-website-id PUBLIC_ENTROLYTICS_HOST=https://entrolytics.click ``` That's it! The integration automatically injects the tracking script and handles View Transitions. ## Configuration Options ### Zero-Config (Recommended) ```ts integrations: [entrolytics()]; // Reads from PUBLIC_ENTROLYTICS_WEBSITE_ID ``` ### Explicit Configuration ```ts entrolytics({ // Required: Your Entrolytics website ID websiteId: "your-website-id", // Optional: Custom host (for self-hosted instances) host: "https://entrolytics.click", // Optional: Auto-track page views (default: true) autoTrack: true, // Optional: Track outbound link clicks (default: true) trackOutboundLinks: true, // Optional: Track file downloads (default: false) trackFileDownloads: false, // Optional: Respect Do Not Track (default: false) respectDnt: false, // Optional: Cross-domain tracking domains: ["example.com", "blog.example.com"], }); ``` ## Runtime Configuration The integration loads the canonical `/script.js` tracker from the configured host. ## Manual Event Tracking For tracking custom events in your Astro components: ```astro --- // In your Astro component --- ``` ### Using the Client Module ```astro --- import { trackEvent } from '@entrolytics/astro/client'; --- ``` ## View Transitions Support The integration automatically works with Astro's View Transitions. Page views are re-tracked on each navigation. ## TypeScript Full TypeScript support included: ```ts import type { EntrolyticsOptions } from "@entrolytics/astro"; const options: EntrolyticsOptions = { websiteId: "your-id", trackOutboundLinks: true, }; ``` ## License MIT License - see [LICENSE](LICENSE) file for details.