Astro SDK

The @entro314labs/entro-astro package provides an Astro integration that automatically injects the Entrolytics tracking script and supports Astro's View Transitions for seamless SPA-like navigation tracking.

Installation

pnpm add @entro314labs/entro-astro

npm install @entro314labs/entro-astro

yarn add @entro314labs/entro-astro

bun add @entro314labs/entro-astro

Quick Start

Add Integration to Astro Config

Add the Entrolytics integration to your astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config'
import entrolytics from '@entro314labs/entro-astro'

export default defineConfig({
  integrations: [
    entrolytics({
      websiteId: import.meta.env.PUBLIC_ENTROLYTICS_WEBSITE_ID,
      host: import.meta.env.PUBLIC_ENTROLYTICS_HOST,
      autoTrack: true,
    }),
  ],
})

Add Environment Variables

Create a .env file:

.env

PUBLIC_ENTROLYTICS_WEBSITE_ID=your-website-id
PUBLIC_ENTROLYTICS_HOST=https://cloud.entrolytics.click

Note: Use the PUBLIC_ prefix to make environment variables available in your Astro components.

Start Tracking

The integration automatically tracks page views. For custom events, use the client module:

src/pages/index.astro

---
// Server-side code (runs at build time)
---

<script>
  import { trackEvent } from '@entro314labs/entro-astro/client'
  
  document.getElementById('signup-btn')?.addEventListener('click', () => {
    trackEvent('signup-click', {
      plan: 'pro',
      source: 'landing-page'
    })
  })
</script>

<button id="signup-btn">Sign Up for Pro</button>

Configuration

Integration Options

interface EntrolyticsOptions {
  /** Website ID (required) */
  websiteId: string
  /** Link ID for link tracking */
  linkId?: string
  /** Pixel ID for conversion tracking */
  pixelId?: string
  /** Custom analytics host URL */
  host?: string
  /** Auto-track page views (default: true) */
  autoTrack?: boolean
  /** Track outbound link clicks (default: true) */
  trackOutboundLinks?: boolean
  /** Track file downloads (default: false) */
  trackFileDownloads?: boolean
  /** Tag for A/B testing */
  tag?: string
  /** Restrict to specific domains */
  domains?: string[]
  /** Strip query params from URLs */
  excludeSearch?: boolean
  /** Strip hash fragments from URLs */
  excludeHash?: boolean
  /** Honor Do Not Track */
  respectDnt?: boolean
  /** Disable on localhost */
  ignoreLocalhost?: boolean
}

Example Configuration

astro.config.mjs

import { defineConfig } from 'astro/config'
import entrolytics from '@entro314labs/entro-astro'

export default defineConfig({
  integrations: [
    entrolytics({
      websiteId: 'abc-123-def',
      host: 'https://analytics.company.com',
      autoTrack: true,
      trackOutboundLinks: true,
      trackFileDownloads: true,
      domains: ['example.com', 'blog.example.com'],
      excludeSearch: true,
      ignoreLocalhost: true,
    }),
  ],
})

Client Module

trackEvent

Track custom events from your Astro components:

src/components/ProductCard.astro

---
export interface Props {
  product: {
    id: string
    name: string
    price: number
  }
}

const { product } = Astro.props
---

<script define:vars={{ product }}>
  import { trackEvent } from '@entro314labs/entro-astro/client'
  
  // Track product view on mount
  trackEvent('product-view', {
    productId: product.id,
    productName: product.name,
    price: product.price
  })
  
  // Track add to cart
  document.getElementById(`add-${product.id}`)?.addEventListener('click', () => {
    trackEvent('add-to-cart', {
      productId: product.id,
      price: product.price
    })
  })
  
  // Track purchase
  document.getElementById(`buy-${product.id}`)?.addEventListener('click', () => {
    trackEvent('purchase', {
      productId: product.id,
      revenue: product.price,
      currency: 'USD'
    })
  })
</script>

<div class="product-card">
  <h3>{product.name}</h3>
  <p>${product.price}</p>
  <button id={`add-${product.id}`}>Add to Cart</button>
  <button id={`buy-${product.id}`}>Buy Now</button>
</div>

identify

Identify logged-in users:

src/components/UserProfile.astro

---
const user = Astro.locals.user
---

{user && (
  <script define:vars={{ user }}>
    import { identify } from '@entro314labs/entro-astro/client'
    
    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: user.subscription,
      company: user.company
    })
  </script>
)}

<div class="user-profile">
  <h2>Welcome, {user.name}!</h2>
</div>

trackPageView

Manually track page views (useful for SPAs or custom routing):

<script>
  import { trackPageView } from '@entro314labs/entro-astro/client'
  
  // Track custom page view
  trackPageView('/virtual-page', 'https://referrer.com')
</script>

View Transitions Support

The integration automatically handles Astro's View Transitions. Page views are re-tracked on each navigation:

src/layouts/Layout.astro

---
import { ViewTransitions } from 'astro:transitions'
---

<html lang="en">
  <head>
    <ViewTransitions />
    <!-- Entrolytics script automatically injected -->
  </head>
  <body>
    <slot />
  </body>
</html>

The integration listens for astro:page-load events and automatically tracks new page views during client-side navigation.

Advanced Usage

Content Collections

Track content views with Astro Content Collections:

src/pages/blog/[...slug].astro

---
import { getCollection, getEntry } from 'astro:content'
import Layout from '@/layouts/Layout.astro'

const { slug } = Astro.params
const post = await getEntry('blog', slug)
---

<Layout title={post.data.title}>
  <script define:vars={{ post: post.data }}>
    import { trackEvent } from '@entro314labs/entro-astro/client'
    
    // Track blog post view
    trackEvent('blog-post-view', {
      title: post.title,
      category: post.category,
      author: post.author,
      publishDate: post.publishDate
    })
  </script>
  
  <article>
    <h1>{post.data.title}</h1>
    <div set:html={post.body} />
  </article>
</Layout>

Project Structure

index.astro

astro.config.mjs

.env

SSR and Static Sites

The integration works with both SSR and static Astro sites:

Static Sites (SSG)

astro.config.mjs

import { defineConfig } from 'astro/config'
import entrolytics from '@entro314labs/entro-astro'

export default defineConfig({
  output: 'static',
  integrations: [
    entrolytics({
      websiteId: 'your-website-id',
    }),
  ],
})

Server-Side Rendering (SSR)

astro.config.mjs

import { defineConfig } from 'astro/config'
import entrolytics from '@entro314labs/entro-astro'
import vercel from '@astrojs/vercel/serverless'

export default defineConfig({
  output: 'server',
  adapter: vercel(),
  integrations: [
    entrolytics({
      websiteId: 'your-website-id',
    }),
  ],
})

TypeScript Support

Full TypeScript support with exported types:

import type {
  EntrolyticsOptions,
  TrackEventData,
  IdentifyTraits,
} from '@entro314labs/entro-astro'

// Type-safe configuration
const options: EntrolyticsOptions = {
  websiteId: 'abc-123',
  trackOutboundLinks: true,
  trackFileDownloads: true,
}

// Type-safe event data
const eventData: TrackEventData = {
  revenue: 99.99,
  currency: 'USD',
  productId: 'pro-plan'
}

Peer Dependencies

astro: >=5.0.0

Features

✅ Astro 5+ integration
✅ Automatic script injection
✅ View Transitions support
✅ Auto-track page views
✅ Outbound link tracking
✅ File download tracking
✅ SSR and SSG support
✅ Content Collections integration
✅ TypeScript-first with full type safety
✅ Zero runtime dependencies

Support

GitHub Issues
Email: hey@entrolytics.click

Astro SDK

E-commerce Integration

Form Tracking

Scroll Depth Tracking

A/B Testing

Outbound Link Tracking

Table of Contents