Overview

@entrolytics/svelte-sdk is the official SvelteKit SDK for Entrolytics - first-party growth analytics for the edge. Add powerful analytics to your Svelte 5 and SvelteKit applications with minimal configuration.

Why use this SDK?

• Zero-config setup with automatic environment detection
• Svelte actions for declarative click tracking
• Svelte stores for reactive state management
• Edge-optimized with sub-50ms response times globally

Key Features

Analytics

• Automatic page view tracking
• Custom event tracking
• User identification
• SvelteKit navigation support

Developer Experience

• use:trackClick Svelte action
• $isLoaded reactive store
• SvelteKit $page store integration
• Full TypeScript support

Quick Start

Installation

npm install @entrolytics/svelte-sdk
# or
pnpm add @entrolytics/svelte-sdk

<!-- +layout.svelte -->
<script>
  import { initEntrolytics } from '@entrolytics/svelte-sdk';

  // Zero-config: automatically reads from .env
  initEntrolytics();
</script>

<slot />

Add to your .env file:

VITE_ENTROLYTICS_WEBSITE_ID=your-website-id
VITE_ENTROLYTICS_HOST=https://entrolytics.click

# Or for SvelteKit static
PUBLIC_ENTROLYTICS_WEBSITE_ID=your-website-id
PUBLIC_ENTROLYTICS_HOST=https://entrolytics.click

Configuration Options

Zero-Config (Recommended)

<script>
  initEntrolytics(); // Reads from env
</script>

Explicit Configuration

initEntrolytics({
  // Required: Your Entrolytics website ID
  websiteId: 'your-website-id',

  // Optional: Custom host (for self-hosted)
  host: 'https://entrolytics.click',

  // Optional: Auto-track page views (default: true)
  autoTrack: true,

  // Optional: Use edge-optimized endpoints (default: true)
  useEdgeRuntime: true,

  // Optional: Respect Do Not Track (default: false)
  respectDnt: false,

  // Optional: Cross-domain tracking
  domains: ['example.com', 'blog.example.com'],
});

Runtime Configuration

The useEdgeRuntime option controls which collection endpoint is used:

Edge Runtime (default) - Optimized for speed and global distribution:

initEntrolytics({
  websiteId: 'your-website-id',
  useEdgeRuntime: true // or omit (default)
});

• Latency: Sub-50ms response times globally
• Best for: Production Svelte/SvelteKit apps, globally distributed users
• Endpoint: Uses /api/send-native for edge-to-edge communication
• Limitations: No ClickHouse export, basic geo data

Node.js Runtime - Full-featured with advanced capabilities:

initEntrolytics({
  websiteId: 'your-website-id',
  useEdgeRuntime: false
});

• Features: ClickHouse export, MaxMind GeoIP (city-level accuracy)
• Best for: Self-hosted deployments, advanced analytics requirements
• Endpoint: Uses /api/send for Node.js runtime
• Latency: 50-150ms (regional)

When to use Node.js runtime:

• Self-hosted Svelte/SvelteKit deployments without edge runtime support
• Applications requiring ClickHouse data export
• Need for advanced geo-targeting with MaxMind
• Custom server-side analytics workflows

Tracking Events

trackEvent

<script>
  import { trackEvent } from '@entrolytics/svelte';

  function handlePurchase() {
    trackEvent('purchase', {
      revenue: 99.99,
      currency: 'USD'
    });
  }
</script>

<button on:click={handlePurchase}>Buy Now</button>

trackClick Action

Use the Svelte action for declarative click tracking:

<script>
  import { trackClick } from '@entrolytics/svelte';
</script>

<button use:trackClick={{ event: 'cta_click', data: { variant: 'hero' } }}>
  Get Started
</button>

Page View Tracking

Automatic (with SvelteKit)

<!-- +layout.svelte -->
<script>
  import { page } from '$app/stores';
  import { initEntrolytics, usePageView } from '@entrolytics/svelte';

  initEntrolytics({ websiteId: 'your-website-id' });
  usePageView(page);
</script>

<slot />

Manual

<script>
  import { trackPageView } from '@entrolytics/svelte';

  // Track current page
  trackPageView();

  // Track specific URL
  trackPageView('/custom-path', 'https://referrer.com');
</script>

User Identification

<script>
  import { identify } from '@entrolytics/svelte';

  // When user logs in
  function handleLogin(user) {
    identify(user.id, {
      email: user.email,
      plan: user.subscription
    });
  }
</script>

Stores

isLoaded

Check if the tracking script is loaded:

<script>
  import { isLoaded } from '@entrolytics/svelte';
</script>

{#if $isLoaded}
  <p>Analytics loaded!</p>
{/if}

TypeScript

Full TypeScript support with exported types:

import type { EntrolyticsOptions } from '@entrolytics/svelte';

License

MIT License - see LICENSE file for details.