Astro SDK | Documentation

The Astro package provides an FlashAnalyticsComponent for layouts, named browser-side helper functions for tracking from islands, and a trackServerError helper for middleware and API routes.

Installation

Install the package

Terminal

npm install @flash-analytics/astro@2.2.3

Terminal

pnpm add @flash-analytics/astro@2.2.3

Add the component to a shared layout

Place the component inside <body> in a layout used by all pages.

src/layouts/Base.astroAstro

---
import { FlashAnalyticsComponent } from '@flash-analytics/astro';

const userId = Astro.locals.user?.id;
---

<html lang="en">
  <body>
    <FlashAnalyticsComponent
      appId={import.meta.env.PUBLIC_FLASH_APP_ID}
      userId={userId}
      capturePageViews
      captureErrors
      captureVariants
    />
    <slot />
  </body>
</html>

Use PUBLIC_ prefix for browser variables

In Astro, only environment variables prefixed with PUBLIC_ are available in the browser. Never expose your secret key as a public variable.

Track events from client islands

src/components/SignupButton.tsTypeScript

import { track, identify } from '@flash-analytics/astro';

document.getElementById('signup-btn')?.addEventListener('click', () => {
  track('signup_clicked', { placement: 'hero' });
});

All client-side imports

TypeScript

import {
  track,
  identify,
  setGlobalProperties,
  revenue,
  getSession,
  assignExperiment,
  autoAssignExperiments,
  getAllExperiments,
  getExperimentById,
  fetchRemoteConfig,
} from '@flash-analytics/astro';

Identify users

TypeScript

import { identify } from '@flash-analytics/astro';

await identify({
  profileId: 'user_123',
  email: 'user@example.com',
  properties: { plan: 'pro' },
});

Experiments

Enable captureVariants on the component for automatic syncing. Use the client helpers to read assignments from any island.

TypeScript

import { getExperimentById, autoAssignExperiments } from '@flash-analytics/astro';

// Cache first, API fallback
const assignment = await getExperimentById('checkout-cta');
console.log(assignment?.variantName);

// Manual refresh
const all = await autoAssignExperiments();

Remote config

TypeScript

import { fetchRemoteConfig } from '@flash-analytics/astro';

const config = await fetchRemoteConfig({ country: 'US' });

const enabled  = config.getBoolean('new_checkout', false);
const title    = config.getString('checkout_title', 'Checkout');
const maxItems = config.getNumber('max_cart_items', 50);

Server-side error tracking

Astro server errors are not captured automatically. Track them from API routes or middleware using trackServerError.

src/pages/api/checkout.tsTypeScript

import { trackServerError } from '@flash-analytics/astro';

export const POST = async ({ request }) => {
  try {
    await processCheckout(await request.json());
    return new Response(JSON.stringify({ ok: true }));
  } 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',
    });
    return new Response(JSON.stringify({ error: 'Failed' }), { status: 500 });
  }
};

Session access

TypeScript

import { getSession } from '@flash-analytics/astro';

const session = getSession();
console.log(session?.id);
console.log(session?.estimatedExpiresAt);
console.log(session?.estimatedTtlMs);