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-sveltenpm install @entro314labs/entro-svelteyarn add @entro314labs/entro-sveltebun add @entro314labs/entro-svelteQuick Start
Initialize in Root Layout
Add Entrolytics to your root layout:
<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:
VITE_ENTROLYTICS_WEBSITE_ID=your-website-id
VITE_ENTROLYTICS_HOST=https://cloud.entrolytics.clickTrack Events
Use the trackEvent function or trackClick action:
<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
<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:
<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:
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:
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
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.tsfiles - ✅ Form actions integration
- ✅ TypeScript-first with full type safety
- ✅ SSR compatible
- ✅ Zero dependencies (besides Svelte)