Trust your numbers from day one. Analytics setup in under 5 minutes.
Trackfa.st is a deployable Next.js boilerplate that automates analytics setup for indie developers and small teams. It provides schema-driven event validation, multi-provider tracking, and real-time health monitoringβeliminating broken tracking and ensuring data quality from the first event.
- π Schema-Safe Events - YAML schema β TypeScript types + Zod validation
- π‘οΈ Edge Validation - Reject invalid events at runtime with detailed errors
- π Multi-Provider Support - PostHog, GA4, Plausible with one API
- π©Ί CLI Doctor - Automated health checks and smoke tests
- β‘ Zero Setup - Clone, configure keys, deploy to Vercel
- π Type-Safe Helpers - Auto-generated tracking functions
# Use this template or clone git clone https://github.com/trackfast/template my-analytics cd my-analytics npm install
Copy .env.local and add your API keys:
# Required - Get from PostHog project settings NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_key_here NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com # Optional - Google Analytics 4 NEXT_PUBLIC_GA4_ID=G-XXXXXXXXXX GA4_API_SECRET=your_measurement_protocol_secret # Optional - Plausible Analytics NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com
# Generate TypeScript types from schema npm run gen:schema # Start development server npm run dev # Test your setup (in another terminal) npm run doctor
import { analytics } from '@/lib/analytics'; // Type-safe event tracking await analytics.signUp('user@example.com', 'starter', 'homepage'); await analytics.pageView('/dashboard'); await analytics.featureUsed('export-data', 'settings-page'); // Business events with validation await analytics.subscriptionCreated('growth', 2900, 'USD'); await analytics.paymentCompleted(2900, 'USD', 'growth');
Edit insight.yml to define your events:
events: user_signed_up: description: "User completed registration" properties: email: type: string required: true description: "User email address" plan: type: enum enum: ["free", "starter", "growth"] required: true source: type: string required: false guards: - email_valid: "email must be valid format" payment_completed: description: "Payment successfully processed" properties: amount: type: number required: true description: "Amount in cents" currency: type: string required: true default: "USD" guards: - amount_positive: "amount must be greater than 0"
Run npm run gen:schema to regenerate TypeScript types and validation.
The CLI doctor performs comprehensive health checks:
npm run doctor
# Test against production
npm run doctor https://yourdomain.comWhat it checks:
- β Environment configuration
- β API endpoint health
- β Schema validation (valid/invalid payloads)
- β Browser tracking simulation
- β End-to-end event flow
Client Event β Middleware Validation β API Route β Multi-Provider Tracking
β β β β
Schema Types β Zod Validation β Enhanced Payload β PostHog/GA4/Plausible
/middleware.ts- Edge validation using generated schemas/src/lib/analytics.ts- Type-safe tracking SDK/src/lib/event-schemas.ts- Generated frominsight.yml/src/app/api/track/route.ts- Multi-provider tracking endpoint/scripts/doctor.ts- Health check and testing tool
- Push to GitHub
- Connect to Vercel
- Add environment variables
- Deploy
# Vercel CLI
vercel env add NEXT_PUBLIC_POSTHOG_KEY
vercel env add NEXT_PUBLIC_GA4_ID
vercel deploy --prodRequired variables:
NEXT_PUBLIC_POSTHOG_KEY- PostHog project API keyNEXT_PUBLIC_POSTHOG_HOST- PostHog instance URL
Optional variables:
NEXT_PUBLIC_GA4_ID- Google Analytics 4 Measurement IDGA4_API_SECRET- GA4 Measurement Protocol API secretNEXT_PUBLIC_PLAUSIBLE_DOMAIN- Your domain for Plausible
- Setup: Create project at posthog.com
- Features: Events, user tracking, session replay, feature flags
- Privacy: EU hosting available, GDPR compliant
- Setup: Create GA4 property, enable Measurement Protocol
- Features: Web analytics, conversion tracking, attribution
- Privacy: Google's standard data practices
- Setup: Add domain at plausible.io
- Features: Privacy-first analytics, no cookies
- Privacy: EU-hosted, fully GDPR compliant
- Edit
insight.yml:
events: custom_action: description: "User performed custom action" properties: action_type: type: enum enum: ["click", "scroll", "hover"] required: true
- Regenerate schemas:
npm run gen:schema
- Use in code:
import { trackEvent } from '@/lib/event-schemas'; await trackEvent('custom_action', { action_type: 'click' });
Extend /src/app/api/track/route.ts:
// Mixpanel example if (process.env.MIXPANEL_TOKEN) { const mixpanelPromise = fetch('https://api.mixpanel.com/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ event, properties: { ...enhancedPayload.properties, token: process.env.MIXPANEL_TOKEN, }, }), }); trackingPromises.push(mixpanelPromise); }
npm run dev- Start development servernpm run build- Build for productionnpm run gen:schema- Generate types from schemanpm run doctor- Run health checksnpm run lint- Run ESLint
trackfast/
βββ insight.yml # Event schema definition
βββ middleware.ts # Edge validation
βββ src/
β βββ lib/
β β βββ analytics.ts # Main tracking SDK
β β βββ event-schemas.ts # Generated schemas (don't edit)
β βββ app/
β βββ api/track/ # Tracking API endpoint
β βββ page.tsx # Demo page
βββ scripts/
βββ gen-schema.ts # Schema code generator
βββ doctor.ts # Health check tool
Events not appearing in PostHog:
- Check API key in environment variables
- Verify network requests in browser dev tools
- Run
npm run doctorfor diagnostics
Schema validation errors:
- Check event name matches
insight.yml - Verify all required properties are provided
- Run
npm run gen:schemaafter schema changes
Middleware errors:
- Ensure
insight.ymlis valid YAML - Check middleware.ts imports are correct
- Verify Zod validation rules
Set environment for detailed logging:
NODE_ENV=development npm run dev
- Auto-dashboard seeder (PostHog API)
- Nightly AI insights via n8n + Claude
- VS Code extension for schema editing
- Trust Score dashboard (0-100 health metric)
- Growth Audit CLI (scan public repos)
- Replay queue for offline events
- Advanced event guards and validation
- Multi-workspace support
- Vercel Marketplace integration
MIT License - feel free to use this for your projects!
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request
Built with β€οΈ for indie developers who want to trust their data