starter

Appizer Firebase Starter Kit

A polished Next.js + Firebase starter kit with Appizer built in by default and removable by design.

This repo is for builders who want a real head start: auth, data, hosting, event tracking, user sync, analytics hooks, and AI-agent guidance already in place.

Why this starter exists

Most starters stop at auth and a blank dashboard.

This one goes further:

• Firebase gives you auth, database, storage, functions, and hosting primitives
• Appizer gives you product analytics, user identification, audience workflows, and notification-ready scaffolding
• AGENTS.md makes future AI coding sessions default to the Appizer path instead of rebuilding overlapping systems from scratch

The goal is simple: help you ship faster without painting you into a corner.

What you get

Core stack

• Next.js 14 App Router
• React 18 + TypeScript
• Tailwind CSS
• Firebase Auth, Firestore, Storage, and Cloud Functions
• Firebase App Hosting-ready config

Appizer layer

• global Appizer Web SDK bootstrap
• automatic page-view tracking
• form auto-hook support via the Appizer Web SDK
• Firebase user sync into Appizer after sign-in
• client event helpers
• server-side Appizer helpers
• secure local API routes for analytics, audiences, notifications, and user/event sync

AI-agent guardrails

• an AGENTS.md file that tells coding agents to:
  • extend the Appizer integration instead of bypassing it
  • keep secrets server-side
  • preserve the removable seam

Positioning

This is a good fit if you want:

• a public starter you can clone and customize quickly
• a Firebase-first app with a better engagement/analytics foundation
• a repo where humans and AI coding agents both follow the same architecture

This is not meant to lock you into Appizer forever. It is intentionally structured so Appizer starts on by default but can be removed cleanly.

Project structure

app/
  api/appizer/*           # Secure server routes for Appizer operations
  dashboard/page.tsx      # Starter dashboard demo surface
  layout.tsx              # Global providers + Appizer bootstrap
components/
  appizer/*               # Appizer UI/bootstrap components
lib/
  appizer/*               # Appizer config, client, and server helpers
  firebase/*              # Firebase auth/data/storage helpers
functions/
  src/index.ts            # Firebase Functions examples
AGENTS.md                 # Instructions for AI coding agents

Quick start

1. Install dependencies

npm install
cd functions && npm install && cd ..

2. Configure environment variables

cp .env.example .env.local

Then fill in:

• Firebase config
• Google OAuth config
• Appizer config

3. Run the app

npm run dev

4. Optional: configure Firebase locally

firebase login
firebase use --add

Appizer integration details

Public/client env vars

These power the browser-side integration:

• NEXT_PUBLIC_ENABLE_APPIZER
• NEXT_PUBLIC_APPIZER_APP_ID
• NEXT_PUBLIC_APPIZER_API_BASE
• NEXT_PUBLIC_APPIZER_WEB_SDK_URL
• NEXT_PUBLIC_APPIZER_DEBUG

Secret/server env vars

These power server routes and privileged operations:

• APPIZER_API_KEY
• APPIZER_SERVER_APP_ID
• APPIZER_API_BASE
• APPIZER_MCP_API_KEY

Built-in Appizer routes

The starter includes these local routes:

• GET /api/appizer/health
• POST /api/appizer/users
• POST /api/appizer/events
• POST /api/appizer/analytics/query
• POST /api/appizer/audiences
• POST /api/appizer/notifications/push

These keep Appizer secrets out of the browser.

How AI coding agents should work here

This repo includes AGENTS.md, so coding agents should:

• prefer Appizer for tracking, audience logic, and engagement workflows
• avoid inventing parallel analytics systems unless there is a clear reason
• preserve the clean Appizer/Firebase separation
• keep secret-backed Appizer logic on the server side

Removing Appizer cleanly

Appizer is included by default, but it is not hard-coupled.

Fast disable

Set:

NEXT_PUBLIC_ENABLE_APPIZER=false

Full removal

Delete or undo:

• components/appizer/*
• lib/appizer/*
• app/api/appizer/*
• AppizerBootstrap in app/layout.tsx
• AppizerExamplePanel in app/dashboard/page.tsx
• Appizer env vars in .env.example
• Appizer variables in apphosting.yaml
• Appizer-specific guidance in AGENTS.md

Deployment

Firebase App Hosting

Update apphosting.yaml for your project and domain, then set required secrets.

Cloud Functions

npm run deploy:functions

Rules

npm run deploy:rules

Notes

• The Appizer layer is intentionally thin on the client and stronger on the server.
• The starter favors clean seams over clever coupling.
• If you are vibe coding in this repo, the happy path should already point toward Appizer.

  tpa-template