Skip to main content

SolidJS / SolidStart

Integrate Swetrix with your SolidJS or SolidStart application to track page views, monitor errors, and capture custom events — all while staying privacy-friendly and GDPR-compliant.

This guide covers both SolidJS SPAs (with Vite) and SolidStart apps with server-side rendering.

Installation​

Install the Swetrix npm package:

npm install swetrix

SolidStart is the official meta-framework for SolidJS with file-based routing and SSR support.

1. Create the analytics component

Create a new file at src/components/Analytics.tsx:

import { onMount } from 'solid-js'
import * as Swetrix from 'swetrix'

export default function Analytics() {
  onMount(() => {
    Swetrix.init('YOUR_PROJECT_ID')
    Swetrix.trackViews()
  })

  return null
}

trackViews() automatically detects client-side route changes, so you only need to call it once.

2. Add it to your root layout

Open src/app.tsx and render the Analytics component inside the <Router>:

import { Router } from '@solidjs/router'
import { FileRoutes } from '@solidjs/start/router'
import Analytics from '~/components/Analytics'

export default function App() {
  return (
    <Router root={(props) => (
      <>
        <Analytics />
        {props.children}
      </>
    )}>
      <FileRoutes />
    </Router>
  )
}
caution

Replace YOUR_PROJECT_ID with your actual Project ID from the Swetrix dashboard, otherwise tracking won't work.

SolidJS with Vite (SPA)​

For a standalone SolidJS SPA without SolidStart, initialise Swetrix in your entry point. trackViews() automatically detects client-side route changes (including @solidjs/router), so a single call is all you need.

Open src/index.tsx:

import { render } from 'solid-js/web'
import * as Swetrix from 'swetrix'
import App from './App'

Swetrix.init('YOUR_PROJECT_ID')
Swetrix.trackViews()

render(() => <App />, document.getElementById('root')!)

Noscript fallback (optional)​

To track visitors who have JavaScript disabled, add a noscript image pixel to your index.html:

<body>
  <div id="root"></div>

  <noscript>
    <img
      src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"
      alt=""
      referrerpolicy="no-referrer-when-downgrade"
    />
  </noscript>
</body>

Disable tracking in development​

By default, Swetrix ignores localhost traffic. You can also explicitly disable it based on your environment:

Swetrix.init('YOUR_PROJECT_ID', {
  disabled: import.meta.env.DEV,
})
tip

If you want to verify tracking locally during development, set devMode: true instead:

Swetrix.init('YOUR_PROJECT_ID', {
  devMode: true,
})

Remember to remove this before deploying to production.

Check your installation​

Build and deploy your application (or temporarily enable devMode) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.

Error tracking​

Enable automatic client-side error monitoring by adding trackErrors() to your initialisation. This captures unhandled JavaScript errors and reports them to Swetrix.

Update your analytics component:

onMount(() => {
  Swetrix.init('YOUR_PROJECT_ID')
  Swetrix.trackViews()
  Swetrix.trackErrors()
})

Errors will appear in the Errors tab of your project dashboard. See the tracking script reference for options like sampleRate and callback.

Tracking custom events​

Custom events let you track specific user interactions — button clicks, form submissions, sign-ups, purchases, and more. Import swetrix in any component and call track().

Example: tracking button clicks​

import * as Swetrix from 'swetrix'

export default function SignUpButton() {
  const handleClick = () => {
    Swetrix.track({
      ev: 'SIGNUP_CTA_CLICK',
      meta: {
        location: 'hero',
      },
    })
  }

  return <button onClick={handleClick}>Sign up</button>
}

Example: tracking form submissions​

import * as Swetrix from 'swetrix'

export default function ContactForm() {
  const handleSubmit = (e: SubmitEvent) => {
    e.preventDefault()

    Swetrix.track({
      ev: 'CONTACT_FORM_SUBMITTED',
      meta: {
        source: 'support_page',
      },
    })

    // ...submit logic
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="you@example.com" required />
      <textarea placeholder="How can we help?" required />
      <button type="submit">Send</button>
    </form>
  )
}

Event naming rules​

Event names must:

  • Contain any characters (including spaces, unicode, etc.)
  • Be no longer than 256 characters

We recommend UPPER_SNAKE_CASE for consistency (e.g. SIGNUP_CTA_CLICK, CONTACT_FORM_SUBMITTED).

Using environment variables for your Project ID​

Rather than hardcoding your Project ID, you can use an environment variable. Since both SolidJS (Vite) and SolidStart use Vite under the hood, prefix the variable with VITE_:

1. Add to your .env file:

VITE_SWETRIX_PID=YOUR_PROJECT_ID

2. Reference it in your analytics component:

Swetrix.init(import.meta.env.VITE_SWETRIX_PID)

Further reading​

Help us improve Swetrix

Was this page helpful to you?

Learn how to contribute•Report a problem with this content