Built for Founders, DIY Builders, and Hobbyists Working with AI Coding Assistants

(And yes, perfectly fine for developers who just want to skip the boilerplate and start building.)

Get Your AI Coding AssistantStart Building Fast

Work with Claude, ChatGPT, or other AI assistants to build cloud-based apps. This template gives them everything they need - authentication, database, deployment - so they can start creating your app immediately.

The Agentic Approach

You have an idea for an app. You describe what you want to Claude or ChatGPT. They write the code. This template gives them a professional foundation to build on - authentication, database, testing, deployment - all pre-configured.

Your AI assistant can be productive immediately instead of spending time setting up infrastructure.

Cloud-Based, Always Available

Your app lives on Google's cloud (Firebase), so it's always available. People use it from their phones, tablets, or computers through a web browser. You don't need to buy servers, configure anything, or worry about technical infrastructure.

Firebase handles scaling automatically - whether you have 10 users or 10,000.

Professional Foundation, Low Cost

This isn't just code that works - it's code built with professional development practices. Automatic testing catches bugs. Automatic deployment means changes go live quickly. Automatic formatting keeps code clean.

Start for $0 with Firebase and GitHub free tiers. Only pay as you grow.

🔥

About This Website

This frontend is educational - it teaches you about professional app development practices. It shows you what your AI coding assistant is working with and why each piece matters.

Once you understand the concepts, you'll replace it with your actual app's interface.

What's Included Out of the Box

Everything you need to build professional apps - authentication, database, testing, deployment - pre-configured and ready to go

1. Security First

Google OAuth, Firebase security rules, HTTPS, environment variables. Built on Google's billion-user infrastructure.

Learn more about security →

2. Authentication

Sign in with Google pre-configured. No passwords to protect. Session management handled automatically.

Try the auth demo →

3. Cloud Database

Firestore NoSQL database with real-time updates. Scales automatically. Free tier is generous.

Try the database demo →

4. Professional Pipeline

Automated testing, deployment, versioning. Changes go from code to production automatically.

See how it works →

Get Started in 5 Minutes

Choose your workflow: Let AI handle setup, or go hands-on

Click the button below to switch between AI-assisted and manual setup

Get Started with AI

Recommended • Fastest Setup

Let AI do the heavy lifting. Your AI coding assistant (Claude Code, Cursor, Windsurf, etc.) handles cloning, dependencies, configuration, and launch. You just provide Firebase credentials.

1

Open in AI Coding Tool

Use Claude Code, Cursor, or your preferred AI assistant

"Set up the NextFire starter template
at github.com/lordquayquays-playground/nextfire-starter"
2

Provide Firebase Credentials

When prompted, share your Firebase project config (from console.firebase.google.com)

AI will guide you through enabling Authentication & Firestore
3

AI Handles Everything Else

Sit back while AI clones, installs dependencies, configures environment, and launches dev server

Clone repo
Install dependencies
Configure .env.local
Launch dev server
4

Start Building!

App running at localhost:3000 - Ready to add your business logic

Total time: 3-5 minutes from start to working app

Why AI-Assisted?

Faster: AI handles boilerplate setup steps instantly
Error-free: AI validates configuration as it goes
Guided: AI explains each step and answers questions
Beginner-friendly: No command-line expertise needed

Next Steps

Start Building!

Replace the demo UI with your app

Auth & database already working
Tests & deployment configured
Focus on your business logic
AI coding guide →

Ready to Build?

You have the foundation. Authentication, database, testing, deployment - all configured. Now add your business logic and watch your idea come to life.

SEE THE TEMPLATE IN ACTION

Interactive demos showing how authentication and database work out of the box.

What these demos show: These examples demonstrate integration patterns—how your frontend connects to Firebase services. The UX you see here is intentionally simple and serves as a teaching tool.

Important concept: The UI is "skin deep"—you can completely replace this design with your own without changing the underlying functionality. The authentication logic, database operations, and security rules work the same regardless of how the interface looks. This separation between presentation (UX) and logic (functionality) is fundamental to professional development.

Leave It to the Pros

Don't build authentication yourself. Delegate to established authentication providers with proven track records. These organizations maintain dedicated security teams, conduct penetration testing, and ensure compliance. You focus on business logic, not security infrastructure.

Email/Password: You Own the Liability

  • When YOU handle passwords, YOU own data breach responsibility
  • One vulnerability affects your entire user base (blast radius)
  • Password reset flows, salt/hash management, breach notifications
  • Legal compliance burden: GDPR, CCPA, data retention policies

OAuth/SSO: Security Experts Handle the Hard Parts

  • Proven Security: Billions of auth events, battle-tested infrastructure
  • Zero Password Liability: Users authenticate with providers you trust
  • Compliance Handled: SOC 2, ISO 27001, GDPR by default
  • Security Updates: Automatic patches from security teams
  • Familiar UX: Users already have accounts, one-click sign-in

Why Spend Resources on Solved Problems?

Building authentication in-house means diverting engineering time from your product to security infrastructure. OAuth providers have already invested millions in securing auth flows, monitoring for threats, and maintaining compliance. Stand on the shoulders of giants—use that time to build features your users actually pay for.

Firebase: Pre-Built Integrations

Firebase Authentication provides turnkey integrations with major providers. Secure token management, session handling, and automatic token refresh—all handled for you.

Major Providers (Built-In)

Google
2B+ users
GitHub
100M+ devs
Microsoft
Enterprise SSO
Meta
3B+ users
Apple
Privacy-first
Twitter/X
Social auth

What's Pre-Configured

  • Google OAuth: Production-ready sign-in flow
  • Custom Hooks: useAuth() for React components
  • Token Management: Automatic refresh & secure storage
  • Security Rules: Role-based access control (RBAC)

Try Live Demo

See OAuth in action. Click to authenticate with Google—no passwords, no liability, just secure sign-in.

🔒 Security: Built on Google's Infrastructure

Your app uses the same security systems that protect Gmail, YouTube, and Google Drive

Security is one of the hardest parts of building apps. Google has invested decades building security systems that protect hundreds of millions of users every day. When you use Firebase (Google's cloud platform), you're using those same security systems.

This template follows Google's recommended practices. You're not inventing security yourself - you're using proven patterns that already protect millions of applications at massive scale.

Think of it like building a house: you don't manufacture your own locks and alarm systems. You use proven, tested security products. Same principle here.

Security Layers: How Protection Works

Security Flow: User to Services

User at Device
→ HTTPS Encrypted →
NextFire App
→ Service Account + RBAC →
Backend Services
AuthFirestoreStorage

Layer 1: User's Browser

Connection: HTTPS (encrypted)|Protection: Data can't be intercepted

Every connection between your user and your app is encrypted with HTTPS. This means data travels through a secure tunnel that hackers can't peek into - like a sealed envelope instead of a postcard. All modern browsers enforce this encryption automatically.

Layer 2: Your App (Next.js)

Sessions: JWT tokens|Secrets: Environment variables

Your application layer handles user sessions with secure JWT tokens (cryptographically signed) and keeps API keys safe in environment variables (never in code). Sessions automatically expire and refresh securely. Service accounts ensure your app authenticates to Firebase with proper credentials.

Layer 3: Firebase Services (Google)

Authentication: Who can sign in
Authorization: Who can access what (RBAC)
Encryption: Data at rest & in transit

Firebase handles the heavy lifting: user authentication (proving who you are), security rules with role-based access control (controlling what you can access based on your role), and automatic encryption of all data both when stored and when transmitted. Google's infrastructure scales to billions of users and is SOC 2, ISO 27001, and GDPR compliant.

You're using security systems that protect billions of users. You're following patterns used by professional teams at companies like Google, Netflix, and Airbnb. You're not figuring out security yourself - you're using what already works at massive scale.

Understanding the Development Stack

From technology foundation to automated production deployment

1

The Foundation: Core Technologies

Building software isn't just about writing code—it requires a coordinated set of tools working together. Think of it like building a house: you need different tools for different jobs. Here are the industry-standard tools you'll see mentioned throughout this documentation.

Important context: All of these tools are free to use, but most are built by passionate developers who maintain them in their spare time or through corporate sponsorship. This generosity powers the entire web.

Understanding the Foundation

Next.js

What it is: A framework for building web applications

Why Next.js: Popular, well-supported, React-based. AI coding assistants (like Claude and ChatGPT) have extensive training on Next.js, making them effective at helping you build.

Alternative frameworks exist (Remix, SvelteKit, Angular, Vue), but Next.js offers the best balance of features, community support, and AI assistant compatibility.

TypeScript

What it is: JavaScript with built-in error checking

Why TypeScript: Catches mistakes before they become bugs. As your code grows, TypeScript helps you manage complexity. Think of it as guardrails for your code.

You could use plain JavaScript, but TypeScript's error-catching saves time in the long run, especially for non-experts.

Firebase

What it is: Google's cloud platform for apps

Why Firebase: No server management. Built-in authentication, database, and hosting. Free tier is generous. Scales automatically as your app grows.

Alternatives include AWS Amplify, Supabase, or traditional cloud services, but they require more technical knowledge to configure.

For non-technical founders: These choices prioritize getting your app built quickly without needing to understand complex infrastructure. The tools below automate the quality and deployment processes that would otherwise require a full engineering team.

Development Environment

VS Code, Cursor: These are code editors where you actually write your software. Think of them as specialized word processors for programmers.

Free, open source, used by millions of developers worldwide

Version Control

Git, GitHub: Git tracks every change to your code over time (like unlimited undo). GitHub stores your code online and enables team collaboration.

Git is free; GitHub is free for public and private projects

Runtime & Packages

Node.js, npm: Node.js runs JavaScript code on your computer. npm (Node Package Manager) lets you install pre-built components built by other developers.

Free, with access to over 2 million open-source packages

Code Quality Tools

TypeScript, ESLint, Prettier: TypeScript catches bugs before they happen. ESLint enforces coding standards. Prettier automatically formats your code consistently.

Free tools that streamline debugging workflows

Testing Frameworks

Jest, Playwright, Vitest: These tools automatically test your code to verify everything works correctly. They catch problems before your users do.

Free, industry-standard testing tools used by major companies

Deployment & CI/CD

Firebase, GitHub Actions: Firebase hosts your application on Google's infrastructure. GitHub Actions automatically tests and deploys your code when you make changes.

Free tier available; Firebase scales with your usage

These are the same tools used by companies like Airbnb, Uber, and Netflix. You're not learning "beginner tools"—you're using professional-grade software that powers the modern web. And yes, it's all free to start.

2

The Development Lifecycle: Why Process Matters

💡

Building an app isn't just writing code

Professional teams follow a process that ensures quality, catches bugs, and deploys safely. This process is called the Software Development Life Cycle (SDLC).

Think of it like building a house: design → build → inspect → move in → maintain. Software is similar: plan → develop → test → deploy → monitor → maintain.

🔄

The 6 Phases Overview

💡
1. Concept
Ideation and market research
📝
2. Plan
Requirements and architecture
👨‍💻
3. Develop
Write code with quality tools
4. Test
Automated quality checks
🚀
5. Deploy
Continuous delivery
📊
6. Monitor
Performance and analytics
3

How This Template Handles Each Phase

This template handles Develop, Test, Deploy, and Monitor - you focus on Concept and Plan

1. Concept

You Handle This

Ideation, market research, and defining what problem you're solving. This is where your vision takes shape.

Your creativity and domain expertise

2. Plan

You Handle This

Requirements gathering, user stories, wireframes, and technical architecture decisions. Define what success looks like.

Your business requirements

3. Develop

Template Provides

Write code with confidence using TypeScript, ESLint, Prettier, and Husky pre-commit hooks to catch issues early.

TypeScript type safety
ESLint + Prettier
Pre-commit hooks

4. Test

Template Provides

Automated testing with Vitest and Playwright ensures your app works as expected before deployment.

Unit tests (Vitest)
E2E tests (Playwright)
CI integration

5. Deploy

Template Provides

Automated deployment to Firebase App Hosting with PR previews, production deployments, and rollback capabilities.

PR preview deployments
Production auto-deploy
99.95% uptime SLA

6. Monitor

Built-in with Firebase

Monitoring comes with Firebase App Hosting from day one. Real-time performance metrics, crash reporting, and user analytics are ready to use immediately.

Performance metrics (built-in)
Crash reporting (built-in)
Analytics & AB testing (enhance)
4

The Automated Development Flow

Your AI assistant writes code. This template handles everything else. When changes are committed, a fully automated pipeline ensures quality, runs tests, and deploys to production—no manual intervention required.

From Code to Production: Fully Automated

1. Develop: Code Quality Checks

What happens: On every save, your code is automatically formatted and linted. Type errors are caught instantly by TypeScript.

Why it matters: Consistent code style across your entire team (human or AI). Bugs caught before you even commit. No 'style discussions' needed.

TypeScriptESLintPrettier

2. Test: All Tests Run Automatically

What happens: When you commit, git hooks run your entire test suite. If tests fail, the commit is blocked. On push, tests run again in the CI pipeline.

Why it matters: Bad code never reaches production. You can't accidentally skip tests. Regressions are caught immediately, not discovered by users.

VitestGit Hooks (Husky)Firebase CI

3. Deploy: Production Delivery

What happens: After all tests pass, Firebase App Hosting automatically builds and deploys your app. Your changes are live in minutes, with zero manual deployment.

Why it matters: Ship features the moment they're ready. No waiting for manual deployments. Consistent deployment process every time. Instant rollback if needed.

Firebase App HostingGlobal CDNAutomatic SSL

4. Monitor: Real-Time Insights

What happens: Firebase provides built-in analytics, performance monitoring, and crash reporting. See how your app performs in production without additional setup.

Why it matters: Know immediately if something breaks. Track real user behavior and performance. Make data-driven decisions about what to build next.

Firebase AnalyticsPerformance MonitoringCrash Reporting
🎉 Your app is live, tested, and monitored!
5

The Professional Stack, Organized by Category

Stop configuring. Start building. Every tool here saves you time and prevents mistakes. This is what professional teams use—now it's yours from day one.

WHY: Confidence in Every Change

Testing & Quality

Know your code works before users see it. Catch bugs early, refactor safely, develop faster.

  • Jest testing framework
  • React Testing Library
  • 70%+ code coverage requirement
  • Firebase Emulators for testing
  • Playwright E2E testing (coming soon)
Catch bugs earlyRefactor safelyFaster dev
WHY: Consistency Without Thinking

Automation

Quality checks run automatically on every commit. Never forget to test, format, or follow conventions.

  • Husky for git hooks
  • Lint-staged pre-commit checks
  • Conventional commits (commitlint)
  • Semantic versioning automation
  • Prettier auto-formatting
Auto qualityConsistent styleAuto releases
WHY: Automated Commit to Production

Deployment

Push code, and it's live. No manual steps. Fast iterations with zero DevOps expertise needed.

  • Firebase App Hosting
  • GitHub Actions CI/CD
  • Automatic preview deployments
  • Zero-config deployment
  • Environment variable management
Fast iterationsNo DevOps neededReliable
WHY: Build Components in Isolation

UI Development

Design and test UI without running full app. Faster development, better component reusability.

  • TailwindCSS 4 for styling
  • Headless UI for accessibility
  • Storybook for components (coming soon)
  • Dark mode support
  • Responsive design built-in
Faster UI devReusableAccessible
WHY: Readable & Maintainable Code

Code Quality

Enforce best practices automatically. Consistent style, fewer bugs, easier collaboration.

  • ESLint for code linting
  • Prettier for formatting
  • TypeScript strict mode
  • Pre-commit hooks
  • Markdown linting
ConsistentFewer bugsTeam-ready
WHY: Onboarding & Collaboration

Documentation

Clear docs help teams move fast. Faster onboarding, better collaboration, easier handoffs.

  • TypeScript for inline docs
  • README guides
  • Code comments
  • API documentation
  • DESIGN.md for architecture
Fast onboardingBetter collabEasy handoff

Coming Soon Features

Technologies marked with "coming soon" are on the roadmap: Playwright for end-to-end testing and Storybook for component development. These will be added as the template evolves based on community needs.

6

What This Means for You

As a founder working with an AI coding assistant:

⏱️

Save Development Time

No manual deployment, testing, or formatting

🐛

Catch bugs before users

Automated tests run before deployment

🚀

Deploy confidently, anytime

CI/CD ensures only working code goes live

🎯

Focus on features

Not infrastructure, deployment, or manual testing

How This Template Automates the Lifecycle

You bring the idea and vision (Concept + Plan). This template handles the technical complexity (Develop + Test + Deploy + Monitor). The result? A professional development workflow that would normally require an entire engineering team—all automated and ready from day one.

Deploy Your Own Instance

Get your copy running in ~15-20 minutes with automated deployment

Recommended

With AI Coding Agent

Best for Claude Code, Cursor, or other AI assistants with Firebase MCP support

Firebase login
Create project
3
Enable billing(manual)
Initialize Firestore
Create web app
Setup environment
Deploy rules
8
Create backend(manual)
Verify deployment
View MCP Guide
Manual CLI

With Shell Script

For developers who prefer command-line automation

./scripts/deploy-firebase.sh
Check prerequisites
Firebase authentication
3
Create project (prompted)(manual)
4
Enable billing (manual)(manual)
Initialize services
Create web app
Deploy rules
Enable App Hosting API
9
Create backend (console)(manual)
View Shell Guide

Need help with a specific step?

Individual how-to guides for each deployment step are available in the maintenance/ directory

After Deployment: What's Next?

Your app is live! The educational frontend you see is temporary - now it's time to build your actual application. Follow these prescriptive workflows for safe, systematic development.

Replace Frontend

Swap the educational UI with your app's interface while keeping Firebase integration intact.

Add Firebase Features

Extend your app with new Firestore collections, authentication providers, and API routes.

Safe Development

Follow git-first workflow with feature branches for all modifications. Never work on main directly.

Development Workflow

  1. 1

    Plan Your App

    What features do you need? What Firebase services?

  2. 2

    Create Feature Branch

    git checkout -b feature/my-feature

  3. 3

    Follow How-Tos

    Use maintenance guides for each task (max 50 lines each)

  4. 4

    Test Locally

    npm run dev and npm test

  5. 5

    Deploy via PR

    Merge to main triggers automatic deployment

For AI Coding Assistants

If you're using Claude Code, Cursor, or other AI assistants, they should follow the established workflows in CLAUDE.md. This template has prescriptive patterns for all common tasks - AI assistants should use these instead of inventing new solutions.

This reduces wheel-spinning and ensures consistent, safe modifications across all developers (human and AI).

🔄 Git & Change Control: Your Code Safety Net

Learn how professional teams manage code changes safely with version control

Understanding Production: Main Branch = What Users See

The most critical concept in professional development

Here's the key insight: The main branch isn't just another branch - it's your production environment. Whatever is in main is what your users actually see and interact with. One bad commit to main affects everyone using your application.

Why This Matters:

If you merge broken code into main, you instantly break the application for all users. That's why professional teams use an audit workflow (Pull Requests) before anything reaches main.

The Audit Workflow: Instead of directly committing to main, you work on a separate feature branch, then create a Pull Request (PR) asking your team to review your changes. Only after review and approval does your code merge into main and reach users.

The Development Flow: From Idea to Production

🌐 PRODUCTION (What Users See)

main branch

✅ Always working

✅ Always deployable

✅ Protected from direct commits

⬇️

1. Create branch

🔒 ISOLATION (Safe Experimentation)

feature/new-feature

Your own workspace

Break things freely

No impact on users

⬇️

2. Work & commit → 3. Push & open PR

🔍 AUDIT CHECKPOINT

Pull Request (PR)

📋 Team reviews code

🧪 Automated tests run

👥 Requires approval

⬇️

4. After approval

⬆️ Merge back to main

Why Audit Before Merging?

Because main = production, we can't afford mistakes. A single bad commit breaks the app for everyone. The audit step (Pull Request review + automated tests) catches problems before they affect users.

Why Feature Branches?

They provide isolation. You can experiment, make mistakes, and iterate without affecting the working application. Multiple developers can work on different features simultaneously without conflicts.

The Result: Protected Production

Users only see code that has been reviewed, tested, and approved. The main branch stays stable and deployable at all times.

Imagine you're writing a book. You make changes, delete paragraphs, add new chapters. What if you accidentally delete something important? What if you want to go back to yesterday's version? That's what Git solves for code.

Git is like an unlimited undo button combined with automatic backup. Every time you save your progress (called a "commit"), Git remembers exactly what your code looked like at that moment. You can always go back to any previous version.

Professional development teams use Git to coordinate work among dozens or hundreds of developers without chaos. This template teaches you those same practices from day one.

How Git Workflow Works

Initial project

main branch

Add authentication

main branch

Create profile page

feature/user-profile branch

Add edit form

feature/user-profile branch

Add tests

feature/user-profile branch

Merge feature/user-profile → v1.1.0

main branch

This diagram shows how features are developed in isolation, then merged back to the main branch when ready.

Core Concepts: Building Blocks of Git

Git as Safety Net

Unlimited Undo for Your Code

Git is version control - it tracks every change you make to your code. Think of it like Word's "Track Changes" feature, but infinitely more powerful.

Time Machine for Code

Go back to any previous version of your code, from minutes ago or months ago.

Automatic Backup

Every commit is a snapshot. Your code history is stored safely, even if your computer crashes.

Fearless Experimentation

Try new ideas without fear. If it doesn't work, just restore the previous version.

Basic Git Workflow

Stage → Commit → Push → Pull Request

The fundamental Git workflow has four main steps that you'll use every day when coding.

1.

Stage (git add)

Select which changes you want to save. Like choosing which photos to add to an album.

2.

Commit (git commit)

Save a snapshot with a message explaining what changed and why.

3.

Push (git push)

Upload your commits to GitHub/GitLab so others can see them and they're backed up in the cloud.

4.

Pull Request (PR)

Ask your team to review your changes before merging them into the main codebase.

Feature Branches

Isolated Workspaces for New Features

A branch is like a parallel universe for your code. You can experiment freely without affecting the main codebase until you're ready.

What They Are

Branches let you work on new features without touching the working code in the main branch.

Why Important

Multiple developers can work on different features simultaneously without conflicts or breaking each other's code.

Naming Examples:

feature/user-authentication
fix/login-bug
refactor/database-queries
chore/update-dependencies

Trunk-Based Development

Keep Main Branch Always Deployable

This template follows trunk-based development - a modern workflow used by high-performing engineering teams.

Main Always Deployable

The main branch should always work perfectly. Never break it. All code there is production-ready.

Short-Lived Branches

Feature branches should live 1-3 days max. Finish features quickly, merge often, deploy frequently.

Frequent Integration

Merge your work back to main multiple times per day. Small, frequent merges prevent conflicts.

Why This Template Uses It:

Trunk-based development enables continuous deployment and rapid iteration - exactly what modern web apps need.

Semantic Versioning

MAJOR.MINOR.PATCH - Meaningful Version Numbers

Semantic versioning (SemVer) is a standardized way to number releases so everyone knows what changed.

MAJORBreaking Changes

Example: 1.x.x → 2.0.0
Changes that break existing code. Users must update their code to use the new version.

MINORNew Features

Example: 1.3.x → 1.4.0
New functionality added, but existing code still works. Backwards compatible.

PATCHBug Fixes

Example: 1.3.4 → 1.3.5
Bug fixes and small improvements. No new features, no breaking changes.

Commitlint & Conventional Commits

Standardized Commit Messages

Conventional commits are a standard format for commit messages. They make your project history clear and enable automated tools.

Format: type(scope): description

feat: Add new feature
Example: feat(auth): add Google login
fix: Bug fix
Example: fix(login): resolve token expiration
chore: Maintenance tasks
Example: chore: update dependencies
docs: Documentation
Example: docs: update README

Why It Matters

Clear history helps you understand what changed, when, and why. Tools can automatically generate changelogs and determine version numbers.

Commitlint Enforces Standards

This template uses commitlint to automatically check your commit messages follow the convention. Bad messages are rejected.

Husky: Git Hooks Guardian

Automatic Quality Gates Before Commit

Husky is your automated quality control system. It runs checks automatically at key moments in your Git workflow to prevent problems before they happen.

What Are Git Hooks?

Git hooks are scripts that run automatically at specific points (like before commit or before push). Husky makes managing them easy.

What Husky Does in This Template:

📝

Pre-commit Hook

Runs ESLint (code quality), Prettier (formatting), and type checks BEFORE you commit. If anything fails, commit is blocked.

Commit-msg Hook

Runs commitlint to validate your commit message follows conventional commits format.

🧪

Pre-push Hook

Runs all tests BEFORE you push to GitHub. Ensures broken code never reaches the remote repository.

Why This Matters

Husky catches problems immediately, when they're easiest to fix. It's like having a senior developer review your work before it reaches the team. Bad code never makes it past your local machine.

Practical Example: Adding a New Feature

Here's how all these concepts work together in a real workflow

1

Create Feature Branch

git checkout -b feature/user-notifications

Isolate your work in a new branch. Main branch stays untouched.

2

Make Changes & Test

Write code, test locally. Husky will validate quality when you commit.

3

Stage & Commit

git add src/components/Notification.tsx git commit -m "feat(notifications): add real-time notification system"

Husky runs pre-commit hooks (lint, format, types) and validates commit message format.

4

Push to Remote

git push origin feature/user-notifications

Husky runs pre-push hooks (all tests). Code backed up to GitHub.

5

Create Pull Request

Open PR on GitHub for team review. CI/CD pipeline runs automated tests. After approval, merge to main.

6

Merge & Tag Release

git tag v1.2.0

Semantic version tag triggers automated deployment. Feature live in production!

Key Takeaways

Professional development practices you're learning with this template

Git is your safety net - unlimited undo, fearless experimentation

Feature branches isolate work - multiple developers, no conflicts

Trunk-based workflow - main always deployable, frequent integration

Semantic versioning - meaningful version numbers communicate changes

Conventional commits - clear history enables automation

Husky enforces quality - catches problems before they spread

These aren't just "best practices" - they're the actual workflows used by professional development teams across the industry, from startups to enterprises. You're learning real industry standards from day one.

🧪

Testing: Your Safety Net

How professional teams catch bugs early, protect UX, and ship with confidence using the Testing Pyramid

1

Why Testing Protects Your Work

⚠️

Without Tests: Fear-Driven Development

😰

Afraid to change code: "If I fix this bug, will I break something else?"

🐛

Manual testing takes forever: Click through the entire app after every change

🔥

Production fires: Users discover bugs before you do

With Tests: Confidence-Driven Development

💪

Refactor fearlessly: Tests tell you immediately if you broke something

Automated quality checks: Seconds instead of hours to verify changes

🛡️

Bugs caught early: Find and fix issues before users see them

Testing isn't about finding bugs—it's about protecting your UX and enabling confident changes. Professional teams write tests not because they're cautious, but because tests let them move faster.

2

The Testing Pyramid: Three Levels

Professional teams use three types of tests, each serving a different purpose. Think of it like security screening at an airport: multiple layers catch different problems.

E2E Testing

Slow • Expensive • High Confidence

Playwright

Integration Testing

Medium • Balanced • Component Groups

Jest + Testing Library

Unit Testing

Fast • Cheap • Isolated Functions

Jest / Vitest

More Tests
Faster
Cheaper

The pyramid shape shows the ratio: Write lots of unit tests, some integration tests, and a few critical E2E tests

Unit Testing

Test individual functions in isolation

Input: 100, 20%
calculateDiscount()
Pure function logic
Output: 80
Milliseconds
Fast execution
🎯
Pinpoint
Exact failure line
💰
Low cost
Easy to maintain
🔄
Continuous
Runs on save
Click to see code

Unit Test Example

Jest/Vitest code

// Function to test
function calculateDiscount(price, percentage) {
  if (price < 0) throw new Error('Price cannot be negative');
  return price * (1 - percentage / 100);
}

// Unit test
test('calculates 20% discount correctly', () => {
  expect(calculateDiscount(100, 20)).toBe(80);
});

test('throws error for negative price', () => {
  expect(() => calculateDiscount(-10, 20)).toThrow();
});

Runs in: ~2ms • Catches: Logic bugs, math errors, edge cases

JestVitestTesting Library
Click to see concept

Integration Testing

Test multiple components working together

User Action
Fill form + click
Component
UserForm
Database
Firestore
Verified Result
UI updated + DB saved
~200ms
Moderate speed
🔗
Real connections
System boundaries
⚖️
Balanced
Setup required
🛡️
Higher trust
Real scenarios
Click to see code

Integration Test Example

React Testing Library + DB

// Integration test: Component + Database
test('user can submit and save form data', async () => {
  // Render the form component
  render(<UserProfileForm userId="123" />);

  // User interaction
  await userEvent.type(screen.getByLabelText('Name'), 'John Doe');
  await userEvent.click(screen.getByRole('button', { name: 'Save' }));

  // Verify database was updated
  const user = await db.users.findById('123');
  expect(user.name).toBe('John Doe');

  // Verify UI feedback
  expect(screen.getByText('Profile saved!')).toBeInTheDocument();
});

Runs in: ~200ms • Catches: Integration bugs, data flow issues, real API problems

JestReact Testing LibraryFirebase Emulator
Click to see concept

E2E Testing

Test complete user flows in a real browser

Page 1: Product
↓ Click "Add to Cart"
Page 2: Cart
↓ Click "Checkout"
Page 3: Payment
↓ Submit Form
Page 4: Success
🐢
~30 seconds
Slow
👤
User view
Real browser
🔧
High cost
Brittle tests
🏆
Highest trust
Full flows
Click to see code

E2E Test Example

Playwright

// E2E test: Complete user journey
test('user can complete checkout flow', async ({ page }) => {
  // Navigate to product page
  await page.goto('/products/123');

  // Add to cart
  await page.click('button:text("Add to Cart")');

  // Go to checkout
  await page.click('a:text("Checkout")');

  // Fill payment form
  await page.fill('[name="cardNumber"]', '4242424242424242');
  await page.fill('[name="email"]', 'test@example.com');

  // Submit order
  await page.click('button:text("Place Order")');

  // Verify success page
  await expect(page).toHaveURL(/\/order-confirmation/);
  await expect(page.locator('h1')).toContainText('Order Confirmed');
});

Runs in: ~30 seconds • Catches: Critical flow breaks, UI regressions, browser bugs

PlaywrightCypressWebdriverIO
Click to see concept

Quick Comparison

AspectUnitIntegrationE2E
Speed⚡ Milliseconds⚡ Hundreds of ms🐢 Seconds to minutes
ScopeSingle functionMultiple componentsEntire user flow
Maintenance💰 Low cost💰💰 Medium cost💰💰💰 High cost
Confidence📊 Logic works📊📊 Systems connect📊📊📊 Users can complete
Recommended Ratio70%20%10%
3

Storybook: Develop React Components in Isolation

Storybook is a component development and testing environment for React. Instead of refreshing your entire app to see component changes, Storybook lets you develop and test components in isolation—viewing all their states instantly without navigating through your full application.

What Storybook Does

  • Component-Level Development: Build and test React components without re-rendering the full page
  • State Exploration: Instantly view all component states (loading, error, empty, success)
  • Component Catalog: Visual library of all UI components and their variations
  • Props Playground: Interactively test different prop combinations

Why Developers Use It

  • Faster Iteration: See changes instantly without navigating through your app
  • Test Component Behaviors: Verify edge cases and interactions without full app context
  • Visual Regression Testing: Catch unintended UI changes automatically
  • Living Documentation: Component catalog that stays in sync with code

Example: Button Component Story

// Button.stories.tsx
export default {
  title: 'Components/Button',
  component: Button,
};

// Story 1: Primary button
export const Primary = () => <Button variant="primary">Click Me</Button>;

// Story 2: Loading state
export const Loading = () => <Button isLoading>Processing...</Button>;

// Story 3: Disabled state
export const Disabled = () => <Button disabled>Can't Click</Button>;

// Story 4: Different sizes
export const Sizes = () => (
  <>
    <Button size="sm">Small</Button>
    <Button size="md">Medium</Button>
    <Button size="lg">Large</Button>
  </>
);

Each "story" shows a different state of the component. Designers can verify the implementation matches their vision, and developers can test edge cases visually without writing code.

4

Playwright: More Than Just E2E

While Playwright is famous for end-to-end testing, it's actually a comprehensive testing platform that handles visual, accessibility, performance, and API testing too. Think of it as your quality assurance Swiss Army knife.

Visual Regression

Takes "golden" screenshots of your UI and compares them on every test run. Catches unintended visual changes.

await expect(page)
  .toHaveScreenshot();
Use case: Design system updates, CSS changes, responsive layouts

Accessibility Testing

Scans your pages for WCAG violations: missing alt text, poor contrast, keyboard navigation issues.

const violations = await
  axe.analyze(page);
Use case: Legal compliance, inclusive design, screen reader support

Cross-Browser

Runs the same tests across Chrome, Firefox, Safari, and mobile browsers automatically.

projects: [
  { name: 'chromium' },
  { name: 'webkit' }
]
Use case: Browser compatibility, vendor-specific bugs

Performance Testing

Measures page load times, network requests, and performance metrics to catch regressions.

const metrics = await
  page.metrics();
expect(metrics.FCP)
  .toBeLessThan(2000);
Use case: Load time budgets, bundle size monitoring

API Testing

Tests backend endpoints directly without the browser—faster than E2E for API validation.

const response = await
  request.get('/api/user');
expect(response.status())
  .toBe(200);
Use case: Backend integration, auth flows, data validation

Comparison Modes

Test the same page across different contexts: light/dark mode, mobile/desktop, logged in/out.

await page.emulateMedia({
  colorScheme: 'dark'
});
Use case: Theme consistency, responsive design, user contexts
5

Team Collaboration: How Storybook Supports Design & Development

While Storybook is primarily a developer tool for component-level testing, it creates valuable alignment between design and engineering teams. Developers use Storybook to build and test components in isolation, and the resulting component catalog serves as a visual reference that both designers and developers can review.

Creative Agency

Design, UX, Visual Guidelines

Responsibilities

  • Design user experience: Information architecture, user flows
  • Create visual language: Colors, typography, spacing, components
  • Create design specs: Document component states, spacing, and interactions
  • Maintain design system: Ensure visual consistency

Deliverables

Design Files
Figma/Sketch designs with specs
Component Specifications
Detailed component behavior and state docs
Design Tokens
CSS variables for colors, spacing, etc.

Application Team

Development, Testing, Deployment

Responsibilities

  • Implement functionality: Business logic, state management, APIs
  • Build in Storybook: Develop and test React components in isolation
  • Write tests: Unit, integration, and E2E tests for quality
  • Integrate components: Connect components to real data and workflows
  • Deploy and maintain: Production operations, monitoring, fixes

Deliverables

Working Application
Functional product with business logic
Storybook + Test Suite
Component catalog and automated tests
Production Deployment
Live, monitored, scalable system

Storybook: Developer Tool with Team Benefits

Developers use Storybook to build and test components without full page re-renders. The resulting component catalog becomes a shared reference that helps align design and development teams.

Design Reference

Designers provide specs for component states (hover, disabled, loading, error, etc.) via design tools

Developer Workflow

Developers build components in Storybook, testing all states in isolation without navigating the full app

Team Alignment

Storybook catalog serves as visual documentation both teams can review to verify implementation

Benefits for Development Teams

Faster iteration: Test component behaviors without re-rendering full application
Component isolation: Develop and debug components independently
Visual catalog: Living documentation that stays in sync with code
Design alignment: Shared visual reference for verifying implementation

Testing: Your Confidence Engine

Professional teams don't write tests because they're cautious—they write tests because tests enable confident, rapid iteration.

🏃‍♂️

Move Faster

Make changes without fear. Tests catch regressions immediately, letting you ship with confidence.

🛡️

Protect UX

Visual regression and E2E tests ensure your user experience stays consistent across changes.

🤝

Collaborate Better

Storybook and tests create shared understanding between designers, developers, and stakeholders.

Design Handoff Workflow

How design agencies communicate with development teams using this template

DESIGN.md is the bridge between UX design and React implementation

The Challenge

Design agencies create beautiful mockups in Figma. Development teams build React components. The gap between these worlds creates friction:

  • Static mockups don't show component structure
  • Interactions and state changes are unclear
  • Responsive behavior gets lost in translation
  • Developers rediscover design intent through trial and error

The Solution

DESIGN.md serves as the handoff document. It combines:

  • Component hierarchy - What components exist and how they nest
  • Layout structure - Grid systems, spacing, responsive breakpoints
  • Interactions - Click handlers, hover states, animations
  • Working HTML - Componentized markup ready to convert to React

The Handoff Workflow

1

Agency Creates

Design Documentation

The design agency builds componentized HTML using tools like Super Design (this very site is an example).

DESIGN.md contains:
  • • Component diagrams
  • • HTML for each component
  • • Layout specifications
  • • Interaction descriptions
2

Dev Team Reviews

Understand Structure

Developers read DESIGN.md to understand the component hierarchy and see working HTML/CSS.

They identify:
  • • React component boundaries
  • • Props and state needs
  • • Reusable patterns
  • • Integration points
3

Convert to React

Implementation

Developers transform the HTML components into React components, adding state, props, and Firebase integration.

Transformation:
  • • HTML → JSX
  • • CSS → Tailwind classes
  • • Static → Interactive
  • • Design → Functional

Important: DESIGN.md vs Storybook

DESIGN.md Purpose:

  • UX design documentation - Shows component structure, layouts, interactions
  • Agency → Dev handoff - Communicates design decisions
  • Pre-implementation - Created before React components exist

Storybook Purpose:

  • React component catalog - Interactive component library
  • Dev tool - For isolated component development and testing
  • Post-implementation - Created from existing React components

Think of it this way: DESIGN.md is the blueprint. Storybook is the catalog of finished components.

From HTML to React Components

Componentized HTML

Agency delivers this in DESIGN.md:

<!-- components/UserCard.html -->
<div class="user-card">
  <img src="avatar.jpg"
       alt="User avatar">
  <h3 class="user-name">
    John Doe
  </h3>
  <p class="user-bio">
    Designer at Acme Corp
  </p>
  <button class="btn-primary">
    Follow
  </button>
</div>
Organized as separate HTML files per component

React Component

Dev team converts to:

// components/UserCard.tsx
export function UserCard({
  user, onFollow
}) {
  return (
    <div className="user-card">
      <img src={user.avatar}
           alt="User avatar" />
      <h3 className="user-name">
        {user.name}
      </h3>
      <p className="user-bio">
        {user.bio}
      </p>
      <button onClick={onFollow}
              className="btn-primary">
        Follow
      </button>
    </div>
  );
}
Adds props, state, and Firebase integration

Benefits of This Workflow

Design Fidelity

Developers implement exactly what designers intended - no guesswork or interpretation gaps

Faster Development

Skip the back-and-forth. HTML structure and CSS are already done. Focus on making it functional.

Clear Collaboration

Designers and developers speak the same language. DESIGN.md is the shared source of truth.

Learn More About the Workflow

For detailed instructions on the design handoff process, component organization, and integration patterns, see INTEGRATION.md in the repository.

Read INTEGRATION.md

Built For AI-Assisted Development

Modern development leverages AI coding assistants to accelerate productivity. This template's clear structure and comprehensive documentation enable AI tools to provide accurate, context-aware assistance.

How AI assistants help: AI coding tools understand well-structured codebases better. With clear patterns, comprehensive documentation (DESIGN.md, DEVELOPMENT.md), and consistent architecture, AI can generate accurate suggestions, explain existing code, and help implement features faster.

You stay in flow, AI handles boilerplate. You focus on business logic, AI handles implementation details. The result: 2-3x faster development with fewer bugs.

MCP Servers: Extending AI Capabilities

Model Context Protocol (MCP) servers give AI assistants access to specialized tools and data sources, making them more effective for frontend development tasks.

Context7

Real-time library documentation (Next.js, React, Firebase, Tailwind)

Docs Retrieval

Git MCP

AI can read git history, diffs, branches, and commits directly

Version Control

Playwright MCP

AI can run browser tests, take screenshots, validate UX flows

Testing & QA

Accessibility MCP

AI validates WCAG compliance, color contrast, screen reader support

A11y Audits

⚠️ Use MCP Servers At Your Own Risk

MCP servers grant AI assistants direct access to your system resources. This enables powerful capabilities but introduces security considerations:

  • Code Execution: MCP servers run code on your machine with your permissions. Malicious servers could access files, modify code, or run harmful commands.
  • Data Access: Servers can read your codebase, git history, environment variables, and local files. This may expose sensitive information like API keys or proprietary code.
  • Network Requests: MCP servers can make outbound connections, potentially exfiltrating data or communicating with external services without your knowledge.
  • Third-Party Code: MCP servers are often community-maintained. Review source code before installation and only use servers from trusted sources.

Best Practices:

• Only install MCP servers from official repositories or trusted maintainers
• Review server code before enabling (check GitHub source)
• Use environment-specific configurations (dev vs production)
• Avoid running MCP servers with elevated privileges
• Keep servers updated to patch security vulnerabilities

This template is optimized for AI-assisted development. Clear architecture, comprehensive docs, and consistent patterns mean AI tools can help you build faster and with fewer mistakes.

Built on the Shoulders of Giants

This template is built on the generosity of open source. When your application generates revenue, please consider supporting these projects that make it all possible.

Give Back to Open Source

These projects depend on community support. Consider sponsoring, contributing code, or spreading the word about the tools that power your success.

Learn How to Contribute