@fresh.codes/astro-pirsch-proxy
v1.0.2
Published
An Astro integration that exposes a Pirsch analytics proxy.
Readme
@fresh.codes/astro-pirsch-proxy
An Astro integration that proxies Pirsch Analytics requests through your server.
Requires an adapter for server rendering such as @astro/node.
Installation
npm install @fresh.codes/astro-pirsch-proxyUsage
Add the integration to your astro.config.mjs:
import { defineConfig } from 'astro/config'
import { loadEnv } from 'vite'
import { pirschProxy } from '@fresh.codes/astro-pirsch-proxy'
const { PIRSCH_ACCESS_TOKEN } = loadEnv(process.env.NODE_ENV, process.cwd(), '')
export default defineConfig({
integrations: [
pirschProxy({
clients: [
{
secret: PIRSCH_ACCESS_TOKEN,
},
],
}),
],
})Create a .env file with your Pirsch access token:
PIRSCH_ACCESS_TOKEN=your-pirsch-access-tokenThe integration will automatically:
- Inject the Pirsch tracking script
- Proxy all analytics requests through your server
- Set up Client Hints headers for better device detection
Configuration
pirschProxy({
// Required: Array of Pirsch API credentials
clients: [
{
id: 'optional-client-id', // OAuth client ID (optional)
secret: 'your-access-token', // Access token or client secret
},
],
// Optional: Customize endpoint paths (default: '/p')
routePrefix: '/analytics',
// Optional: Customize endpoint names
endpointNames: {
script: 'script.js', // default: 'p.js'
hit: 'hit', // default: 'h'
event: 'event', // default: 'e'
session: 'session', // default: 's'
},
// Optional: Disable automatic script injection (default: true)
injectScript: false,
// Optional: Disable Client Hints headers (default: false)
disableClientHints: true,
// Optional: Enable debug logging (default: false)
debug: true,
// Optional: Request timeout in ms (default: 5000)
timeout: 10000,
// Optional: Script cache TTL in ms (default: 600000)
scriptCacheTTL: 300000,
})Manual Script Injection
If you want full control over the Pirsch script attributes, disable automatic injection and use the PirschScript component.
First, configure the integration:
// astro.config.mjs
export default defineConfig({
integrations: [
pirschProxy({
clients: [{ secret: 'token' }],
injectScript: false, // Disable automatic injection
}),
],
})Then use the PirschScript component in your layout:
---
// src/layouts/Layout.astro
import PirschScript from '@fresh.codes/astro-pirsch-proxy/components/PirschScript.astro'
---
<html>
<head>
<PirschScript data-enable-sessions='true' data-interval-ms='60000' />
</head>
<body>
<slot />
</body>
</html>The component automatically configures the script src and endpoint data attributes. You can pass any additional Pirsch script attributes as props.
Usage with Swup
When using Swup for page transitions, you'll need to prevent the script from being re-processed on navigation. Use manual script injection and add the data-swup-ignore-script attribute:
---
import PirschScript from '@fresh.codes/astro-pirsch-proxy/components/PirschScript.astro'
---
<PirschScript data-swup-ignore-script />This prevents Swup from re-executing the analytics script on each navigation, which would cause duplicate page view tracking.
TypeScript Support
Add the following to your src/env.d.ts:
/// <reference types="@fresh.codes/astro-pirsch-proxy/client" />Add the following to your src/global.d.ts:
import type { Scalar } from '@fresh.codes/astro-pirsch-proxy'
declare global {
function pirsch(
event: string,
meta?: {
duration?: number
meta?: Record<string, Scalar>
},
): void
}
export {}Publishing
# Update version (patch, minor, or major)
npm version patch
# Push code and tags
git push && git push --tags
# Publish to npm
npm publish --access public
# Create GitHub release
gh release create v$(node -p "require('./package.json').version") --generate-notesLicense
Made by Fresh Codes.
Don't have Pirsch yet? Sign up here (affiliate link).