@flash-analytics/astro
v2.2.0
Published
Analytics and error tracking for Astro apps.
Readme
Flash Analytics Astro SDK
Analytics and error tracking for Astro apps.
Install
npm install @flash-analytics/astroQuick Start
Add the Flash Analytics component to your Astro layout:
---
import { FlashAnalyticsComponent } from '@flash-analytics/astro';
---
<html>
<head>
<FlashAnalyticsComponent
appId="your-app-id"
endpoint="https://api.flashanalytics.app"
capturePageViews
/>
</head>
<body>
<slot />
</body>
</html>Auto-Tracked Events
| Event | Trigger |
|---|---|
| page_view | Every page navigation when capturePageViews is enabled |
| js_error | Uncaught JS exceptions when captureErrors is enabled |
| unhandled_promise_rejection | Unhandled promise rejections when captureErrors is enabled |
Note:
server_erroris manual in Astro — you calltrackServerError()yourself in middleware or API routes. This contrasts with Express whereserver_erroris captured automatically by the error middleware.
Manual Tracking
import { track, identify } from '@flash-analytics/astro';
// Track a custom event
track('signup_completed', { plan: 'pro' });
// Identify a user
identify({ profileId: 'user-123', email: '[email protected]' });Session Access
import { getSession } from '@flash-analytics/astro';
const session = getSession();
console.log(session?.id);
console.log(session?.estimatedExpiresAt);
console.log(session?.estimatedTtlMs);Experiment Assignment
Enable captureVariants on the component for automatic assignment on session start and identify():
<FlashAnalyticsComponent
appId="your-app-id"
capturePageViews
captureVariants
/>For manual assignment or finer control, use the exported functions:
import { assignExperiment, autoAssignExperiments } from '@flash-analytics/astro';
// Single experiment
const variant = await assignExperiment('checkout-cta');
// All eligible experiments at once
const assignments = await autoAssignExperiments({ modes: ['session'] });Error Tracking
Enable captureErrors to automatically capture client-side JS errors and unhandled promise rejections as js_error and unhandled_promise_rejection. No extra credentials needed — the component uses the SDK's own appId / secretKey / endpoint:
<FlashAnalyticsComponent
appId="your-app-id"
endpoint="https://api.flashanalytics.app"
capturePageViews
captureErrors
/>Server-side errors (Astro middleware, API routes) must be tracked manually using trackServerError():
import { trackServerError } from '@flash-analytics/astro';
// In Astro middleware or an API route:
try {
await riskyOperation();
} catch (err) {
await trackServerError(err, {
clientId: import.meta.env.FLASH_CLIENT_ID,
clientSecret: import.meta.env.FLASH_CLIENT_SECRET,
apiUrl: 'https://api.flashanalytics.app/track',
});
// optionally pass a custom event name as the third argument (default: 'server_error')
}trackServerError() sends a server_error event directly from the server, so the secret key never reaches the browser.