π Open source, privacy-first web analytics β a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
Preact guide
Blue Moused4f11310b19f
diff --git a/docs/docs/integration-guides.md b/docs/docs/integration-guides.mdindex 35c739718..868b08a3d 100644--- a/docs/docs/integration-guides.md+++ b/docs/docs/integration-guides.md@@ -41,6 +41,7 @@ Swetrix integrates with a wide range of platforms, frameworks, and tools. Choose- [Jekyll](/jekyll-integration)- [Next.js](/nextjs-integration)- [Nuxt](/nuxt-integration)+- [Preact](/preact-integration)- [Qwik / Qwik City](/qwik-integration)- [React (Vite / CRA)](/react-integration)- [Remix](/remix-integration)diff --git a/docs/docs/integrations/preact.md b/docs/docs/integrations/preact.mdnew file mode 100644index 000000000..0ff6f339d--- /dev/null+++ b/docs/docs/integrations/preact.md@@ -0,0 +1,239 @@+---+title: Preact+slug: /preact-integration+---++Integrate Swetrix with your [Preact](https://preactjs.com/) application to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++This guide covers Preact apps built with **Vite**, the **Preact CLI**, or any other bundler.++## Installation++Install the Swetrix npm package:++```bash+npm install swetrix+```++### Basic setup (single-page apps without routing)++If your app doesn't use client-side routing, you can initialise Swetrix once in your entry point.++Open `src/index.tsx` (or `src/index.jsx`):++```tsx+import { render } from 'preact'+import * as Swetrix from 'swetrix'+import App from './App'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()++render(<App />, document.getElementById('app')!)+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### With preact-router or preact-iso++`trackViews()` automatically detects client-side route changes (including `preact-router` and `preact-iso` navigations), so you only need to call it once. Initialise Swetrix in your entry point the same way as above β no route-change listener needed.++### Noscript fallback (optional)++To track visitors who have JavaScript disabled, add a noscript image pixel to your `index.html`:++```html+<body>+ <div id="app"></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:++```tsx+Swetrix.init('YOUR_PROJECT_ID', {+ disabled: import.meta.env.DEV, // Vite+ // disabled: process.env.NODE_ENV === 'development', // Preact CLI / webpack+})+```++:::tip+If you want to verify tracking locally during development, set `devMode: true` instead:++```tsx+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 setup:++```tsx+import { useEffect } from 'preact/hooks'+import * as Swetrix from 'swetrix'++export default function App() {+ useEffect(() => {+ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackViews()+ Swetrix.trackErrors()+ }, [])++ return <main>{/* your app */}</main>+}+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) 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++```tsx+import * as Swetrix from 'swetrix'++export default function SignUpButton() {+ const handleClick = () => {+ Swetrix.track({+ ev: 'SIGNUP_CTA_CLICK',+ meta: {+ location: 'navbar',+ },+ })+ }++ return <button onClick={handleClick}>Sign up</button>+}+```++### Example: tracking form submissions++```tsx+import * as Swetrix from 'swetrix'++export default function ContactForm() {+ const handleSubmit = (e: Event) => {+ e.preventDefault()++ Swetrix.track({+ ev: 'CONTACT_FORM_SUBMITTED',+ meta: {+ source: 'support_page',+ },+ })++ // ...submit logic+ }++ return (+ <form onSubmit={handleSubmit}>+ <input type="email" placeholder="[email protected]" required />+ <textarea placeholder="How can we help?" required />+ <button type="submit">Send</button>+ </form>+ )+}+```++### Example: tracking outbound links++Create a reusable component for external links:++```tsx+import * as Swetrix from 'swetrix'+import type { ComponentChildren } from 'preact'++interface TrackedLinkProps {+ href: string+ children: ComponentChildren+ eventName?: string+}++export default function TrackedLink({+ href,+ children,+ eventName = 'OUTBOUND_CLICK',+}: TrackedLinkProps) {+ const handleClick = () => {+ Swetrix.track({+ ev: eventName,+ meta: { url: href },+ })+ }++ return (+ <a href={href} target="_blank" rel="noopener noreferrer" onClick={handleClick}>+ {children}+ </a>+ )+}+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++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.++**Vite** β prefix with `VITE_`:++```+VITE_SWETRIX_PID=YOUR_PROJECT_ID+```++```tsx+Swetrix.init(import.meta.env.VITE_SWETRIX_PID)+```++**Preact CLI / webpack** β prefix with `PREACT_APP_`:++```+PREACT_APP_SWETRIX_PID=YOUR_PROJECT_ID+```++```tsx+Swetrix.init(process.env.PREACT_APP_SWETRIX_PID!)+```++## Using React compat aliases++If your project uses `preact/compat` to alias `react` and `react-dom`, Swetrix works identically to a standard React setup. No additional configuration is needed β the Swetrix npm package doesn't depend on React internals.++## Further reading++- [React integration](/react-integration) β if you're using React instead of Preact, follow the React guide.+- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.diff --git a/docs/sidebars.js b/docs/sidebars.jsindex b6013788d..755781fba 100644--- a/docs/sidebars.js+++ b/docs/sidebars.js@@ -40,6 +40,7 @@ module.exports = {items: ['integrations/gatsby','integrations/nextjs',+ 'integrations/preact','integrations/react','integrations/remix',],