Svelte SDK

SvelteKit integration and Svelte actions for Entrolytics

Svelte SDK

The @entro314labs/entro-svelte package provides SvelteKit integration, Svelte stores, and declarative actions for tracking analytics in Svelte 5 and SvelteKit 2 applications.

Installation

pnpm add @entro314labs/entro-svelte
npm install @entro314labs/entro-svelte
yarn add @entro314labs/entro-svelte
bun add @entro314labs/entro-svelte

Quick Start

Initialize in Root Layout

Add Entrolytics to your root layout:

src/routes/+layout.svelte
<script lang="ts">
  import { initEntrolytics, usePageView } from '@entro314labs/entro-svelte'
  import { page } from '$app/stores'
  
  // Initialize Entrolytics
  initEntrolytics({
    websiteId: import.meta.env.VITE_ENTROLYTICS_WEBSITE_ID,
    host: import.meta.env.VITE_ENTROLYTICS_HOST,
    autoTrack: true,
  })
  
  // Auto-track page views on navigation
  usePageView(page)
</script>

<slot />

Add Environment Variables

Create a .env file:

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

Track Events

Use the trackEvent function or trackClick action:

src/routes/+page.svelte
<script lang="ts">
  import { trackEvent, trackClick } from '@entro314labs/entro-svelte'
  
  function handleSignup() {
    trackEvent('signup', {
      plan: 'pro',
      source: 'landing-page'
    })
  }
</script>

<!-- Programmatic tracking -->
<button on:click={handleSignup}>
  Sign Up for Pro
</button>

<!-- Declarative tracking with actions -->
<button use:trackClick={{ event: 'cta-click', data: { location: 'hero' } }}>
  Get Started
</button>

Configuration

Initialization 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
  /** 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

src/routes/+layout.svelte
<script lang="ts">
  import { initEntrolytics } from '@entro314labs/entro-svelte'
  
  initEntrolytics({
    websiteId: 'abc-123-def',
    host: 'https://analytics.company.com',
    autoTrack: true,
    domains: ['example.com', 'app.example.com'],
    excludeSearch: true,
    ignoreLocalhost: true,
  })
</script>

Tracking Functions

trackEvent

Track custom events:

<script lang="ts">
  import { trackEvent } from '@entro314labs/entro-svelte'
  
  function handlePurchase(product: Product) {
    trackEvent('purchase', {
      revenue: product.price,
      currency: 'USD',
      productId: product.id,
      category: product.category
    })
  }
  
  function handleAddToCart() {
    trackEvent('add-to-cart', {
      productId: product.id,
      quantity: 1
    })
  }
</script>

<button on:click={handlePurchase}>
  Buy Now - ${product.price}
</button>

trackPageView

Manually track page views:

<script lang="ts">
  import { trackPageView } from '@entro314labs/entro-svelte'
  import { onMount } from 'svelte'
  
  onMount(() => {
    // Track current page
    trackPageView()
    
    // Or track with custom URL and referrer
    trackPageView('/custom-path', 'https://referrer.com')
  })
</script>

identify

Identify logged-in users:

<script lang="ts">
  import { identify } from '@entro314labs/entro-svelte'
  
  function handleLogin(user: User) {
    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: user.subscription,
      company: user.company
    })
  }
</script>

Svelte Actions

trackClick

Declaratively track click events:

<script lang="ts">
  import { trackClick } from '@entro314labs/entro-svelte'
</script>

<!-- Basic usage -->
<button use:trackClick={{ event: 'button-click' }}>
  Click Me
</button>

<!-- With custom data -->
<button use:trackClick={{ 
  event: 'cta-click',
  data: { 
    location: 'hero',
    variant: 'primary' 
  }
}}>
  Get Started
</button>

<!-- Track external links -->
<a 
  href="https://external-site.com"
  use:trackClick={{ 
    event: 'outbound-link',
    data: { destination: 'external-site.com' }
  }}
>
  External Link
</a>

trackVisible

Track when elements become visible:

<script lang="ts">
  import { trackVisible } from '@entro314labs/entro-svelte'
</script>

<!-- Track when hero section is visible -->
<section use:trackVisible={{ 
  event: 'section-viewed',
  data: { section: 'hero' }
}}>
  <h1>Welcome to our site</h1>
</section>

<!-- Track with threshold -->
<div use:trackVisible={{
  event: 'pricing-viewed',
  data: { section: 'pricing' },
  threshold: 0.5  // 50% visible
}}>
  Pricing content
</div>

SvelteKit Integration

Page View Tracking

Automatically track page views with SvelteKit navigation:

src/routes/+layout.svelte
<script lang="ts">
  import { page } from '$app/stores'
  import { initEntrolytics, usePageView } from '@entro314labs/entro-svelte'
  
  initEntrolytics({
    websiteId: import.meta.env.VITE_ENTROLYTICS_WEBSITE_ID,
  })
  
  // Automatically track page changes
  usePageView(page)
</script>

<slot />

Server-Side Tracking

Track events from SvelteKit server routes:

src/routes/api/subscribe/+server.ts
import { json } from '@sveltejs/kit'
import type { RequestHandler } from './$types'

export const POST: RequestHandler = async ({ request, fetch }) => {
  const data = await request.json()
  
  // Track server-side event
  await fetch('https://cloud.entrolytics.click/api/send', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'event',
      payload: {
        website: import.meta.env.VITE_ENTROLYTICS_WEBSITE_ID,
        name: 'subscription-created',
        data: {
          plan: data.plan,
          amount: data.amount,
        }
      }
    })
  })
  
  return json({ success: true })
}

Form Actions

Track in SvelteKit form actions:

src/routes/contact/+page.server.ts
import type { Actions } from './$types'

export const actions: Actions = {
  default: async ({ request, fetch }) => {
    const formData = await request.formData()
    
    // Track form submission
    await fetch('https://cloud.entrolytics.click/api/send', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        type: 'event',
        payload: {
          website: import.meta.env.VITE_ENTROLYTICS_WEBSITE_ID,
          name: 'contact-form-submit',
          data: {
            hasCompany: !!formData.get('company'),
          }
        }
      })
    })
    
    // Process form...
    return { success: true }
  }
}

Stores

isLoaded

Reactive store that indicates whether the tracking script has loaded:

<script lang="ts">
  import { isLoaded } from '@entro314labs/entro-svelte'
</script>

{#if $isLoaded}
  <p>✓ Analytics loaded and ready</p>
{:else}
  <p>Loading analytics...</p>
{/if}

config

Access the current Entrolytics configuration:

<script lang="ts">
  import { config } from '@entro314labs/entro-svelte'
</script>

<div>
  Website ID: {$config.websiteId}
  Host: {$config.host}
</div>

Advanced Usage

Project Structure

+layout.svelte
+page.svelte
.env

TypeScript Support

Full TypeScript support with exported types:

import type {
  EntrolyticsOptions,
  TrackEventData,
  IdentifyTraits,
  TrackClickOptions,
  TrackVisibleOptions,
} from '@entro314labs/entro-svelte'

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

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

// Type-safe action parameters
const clickOptions: TrackClickOptions = {
  event: 'button-click',
  data: { location: 'hero' }
}

Peer Dependencies

  • svelte: >=5.0.0

Features

  • ✅ Svelte 5 and SvelteKit 2 support
  • ✅ Declarative Svelte actions (trackClick, trackVisible)
  • ✅ Reactive Svelte stores
  • ✅ Auto-track page views with SvelteKit navigation
  • ✅ Server-side tracking in +server.ts files
  • ✅ Form actions integration
  • ✅ TypeScript-first with full type safety
  • ✅ SSR compatible
  • ✅ Zero dependencies (besides Svelte)

Support