Plausible Analytics integration for Expo
npm install expo-plausiblePlausible Analytics integration for Expo apps. Lightweight provider + hook to send events to the Plausible Events API, with optional offline queueing and batch flushing.
- Install: pnpm add expo-plausible
- Provider + hook: PlausibleProvider, useTrackEvent
- Offline ready: enqueue on failure and flush later
- Batching: optionally send queued events in batches
- Consent helpers: enable/disable tracking at runtime
``bash`
pnpm add expo-plausible
Wrap your app with PlausibleProvider, then call useTrackEvent() where you need it.
`tsx
import React from 'react';
import { Text, View, Button } from 'react-native';
import { PlausibleProvider, useTrackEvent } from 'expo-plausible';
function Screen(): JSX.Element {
const trackEvent = useTrackEvent();
async function onSignup(): Promise
await trackEvent({
name: 'Signup',
url: 'https://your-app.example/signup',
props: { plan: 'Pro' },
});
}
return (
);
}
export default function App(): JSX.Element {
return (
);
}
`
- Set batch: true on the provider to enable batch flushing of the offline queue.
- When the queue is flushed with batching enabled, events to the same endpoint are sent as a single POST containing an array of event bodies.
`tsx
import { PlausibleProvider } from 'expo-plausible';
function Root(): JSX.Element {
return (
{/ ... /}
);
}
`
You can also manually flush at any time:
`ts
import { flushQueue } from 'expo-plausible';
await flushQueue({ batch: true });
`
- The provider defaults enableOfflineQueue to true.enableOfflineQueue
- If a network error or non-2xx response occurs when sending an event, the event is persisted and retried later.
- The queue is automatically flushed on mount when is true.
Manual control:
`ts
import { flushQueue } from 'expo-plausible';
const sentCount = await flushQueue(); // uses global fetch by default
`
You can toggle analytics at runtime. When disabled, new events are dropped and any queued events are cleared on flush.
`ts
import { enableTracking, disableTracking, isTrackingEnabled, flushQueue } from 'expo-plausible';
disableTracking();
console.log(isTrackingEnabled()); // false
// Later, e.g. after user consent
enableTracking();
await flushQueue();
`
Child providers override only the fields they specify and inherit the rest from parents.
`tsx
import { PlausibleProvider } from 'expo-plausible';
export function App(): JSX.Element {
return (
{/ Child overrides domain but inherits apiHost and batch /}
{/ screens /}
);
}
`
- PlausibleProvider({ config })domain: string
- (required)apiHost?: string
- (default https://plausible.io)enableOfflineQueue?: boolean
- (default true)batch?: boolean
- (default false)useTrackEvent()
- → (request) => Promiserequest = { name: string; url: string; domain?: string; props?: Record
- flushQueue(options?)
- → Promiseoptions = { batch?: boolean; fetchImpl?: typeof fetch }
- enableTracking()
- / disableTracking() / isTrackingEnabled()
See Plausible’s official Events API documentation: https://plausible.io/docs/events-api
Contributions are welcome!
- Issues: Please open an issue describing the problem or proposal.
- PRs: Keep changes focused. Include tests where applicable.
- Code style: TypeScript, clear naming, early returns, meaningful error handling.
- Testing: Run pnpm test and ensure coverage doesn’t regress.pnpm build
- Build: Run before publishing; CI will verify types and lint.
Local setup:
`bash`
pnpm install
pnpm test
pnpm build
By contributing, you agree to license your contributions under the MIT License of this repository.
MIT — see LICENSE` for details.