SaaS Starter Kit

A production-ready, type-safe SaaS starter kit with React frontend and FastAPI backend. Built with modern development practices, comprehensive testing, and automated CI/CD pipelines.

Features

Type-Safe Full Stack: TypeScript frontend + Python backend with Pydantic validation
Modern Development: Hot reload with Docker Compose Watch for rapid iteration
Comprehensive Testing: Unit, integration, and E2E tests with coverage reporting
Automated CI/CD: GitHub Actions for testing, building, and deployment
Code Quality: Automated linting, formatting, and pre-commit hooks
API Client Generation: Type-safe frontend API client from OpenAPI schema
Database Ready: PostgreSQL with future Alembic migration support
Caching Layer: Redis for caching and pub/sub
Developer Tooling: VS Code debugging, Husky hooks, Conventional Commits
Production Ready: Docker multi-stage builds, health checks, monitoring ready

Documentation

This project uses Starlight for documentation. The full documentation covers architecture, development workflows, API reference, deployment, and guides.

Running the Documentation Locally

cd docs
npm install
npm run dev

The documentation will be available at http://localhost:4321

Documentation Links

When running locally, explore these sections:

Getting Started - Introduction and quick start guide
Architecture Overview - System design and patterns
Development Guide - Local setup and Docker workflow
API Reference - REST API documentation
Deployment Guide - CI/CD pipelines and deployment
API Documentation - OpenAPI/Swagger docs (when backend is running)

Quick Start

Prerequisites

Docker Desktop 4.24+ (includes Docker Compose v2.22+)
Node.js 20+ (for local development)
Python 3.11+ (for local development)
Git 2.40+

1. Clone the repository

git clone <repository-url>
cd starterkit

2. Setup environment variables

# Backend
cp backend/.env.example backend/.env

# Frontend
cp frontend/.env.example frontend/.env

3. Start with Docker Compose Watch

# Start all services with hot reload
docker compose up --watch

# Or use the dedicated watch command
docker compose watch

This will start:

Frontend: http://localhost:5173
Backend API: http://localhost:8000
API Docs: http://localhost:8000/api/docs
PostgreSQL: localhost:5432
Redis: localhost:6379

4. Verify everything is running

# Check backend health
curl http://localhost:8000/health

# Check frontend
open http://localhost:5173

Project Structure

starterkit/
├── .github/              # GitHub Actions workflows
│   ├── workflows/       # CI/CD pipeline definitions
│   └── actions/         # Reusable workflow actions
├── frontend/            # React + Vite frontend
│   ├── src/            # Source code
│   │   ├── components/ # React components
│   │   ├── api/        # Generated API client
│   │   └── utils/      # Utility functions
│   ├── public/         # Static assets
│   └── emails/         # React Email templates (future)
├── backend/            # FastAPI backend
│   ├── app/            # Application code
│   │   ├── api/        # API endpoints
│   │   ├── core/       # Core functionality
│   │   ├── models/     # SQLAlchemy models (future)
│   │   └── schemas/    # Pydantic schemas
│   ├── tests/          # Test files
│   ├── alembic/        # Database migrations (future)
│   └── scripts/        # Utility scripts
├── shared/             # Shared types & constants
├── docker/             # Docker configurations (future)
├── docs/               # Starlight documentation site
└── .husky/             # Git hooks

Development Commands

All commands can be run from the root directory:

Linting & Formatting

# Lint all code (frontend + backend)
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format all code
npm run format

# Check formatting without changes
npm run format:check

Testing

# Run all tests (backend + frontend)
npm test

# Run backend tests only
npm run test:backend

# Run frontend tests only
npm run test:frontend

# Generate coverage reports
npm run test:coverage

# Watch mode (auto-run tests on changes)
npm run test:watch

Type Checking

# Run TypeScript type checking
npm run typecheck

Docker Commands

# Start all services with watch mode
docker compose up --watch

# Start services in background
docker compose up -d

# Stop all services
docker compose down

# View logs
docker compose logs -f

# Rebuild containers
docker compose build

# Clean rebuild (remove volumes)
docker compose down -v && docker compose build --no-cache

Running Commands Inside Containers

# Backend shell
docker compose exec backend bash

# Frontend shell
docker compose exec frontend sh

# Run backend tests
docker compose exec backend pytest

# Run frontend tests
docker compose exec frontend npm test

# Install new Python package
docker compose exec backend poetry add <package-name>

# Install new npm package
docker compose exec frontend npm install <package-name>

Database Operations

# Connect to PostgreSQL
docker compose exec postgres psql -U postgres -d starterkit

# Run migrations (when available)
docker compose exec backend alembic upgrade head

# Create new migration
docker compose exec backend alembic revision --autogenerate -m "description"

API Client Generation

# Export OpenAPI schema from backend
cd backend
poetry run python scripts/export_openapi.py

# Generate frontend API client
cd ../frontend
npm run generate:api

When to regenerate:

After adding/modifying backend endpoints
After changing Pydantic schemas
After pulling changes from git (if API changed)
Before building for production

Testing

Backend Testing (Pytest)

Unit Tests: Test individual functions and classes
Integration Tests: Test API endpoints and database operations
Coverage: Configured for 80% minimum coverage
Async Support: Full support for async/await patterns
Factories: Test data creation with Factory pattern

Run backend tests:

npm run test:backend
npm run test:backend:coverage  # With coverage report

Frontend Testing (Vitest)

Component Tests: React Testing Library for component testing
Integration Tests: Test component interactions
Coverage: HTML, JSON, and LCOV reports
Fast: Vitest provides instant feedback with HMR

Run frontend tests:

npm run test:frontend
npm run test:frontend:coverage  # With coverage report

E2E Testing (Future)

Playwright: Browser automation for end-to-end tests
Real Browser: Test in Chrome, Firefox, Safari
CI Integration: Automated E2E tests in CI pipeline

Tech Stack

Backend

Technology	Version	Purpose
FastAPI	0.109	Modern Python web framework
PostgreSQL	16	Primary database
Redis	7	Caching & pub/sub
SQLAlchemy	2.0	Async ORM (coming soon)
Pydantic	2.5	Data validation
Uvicorn	Latest	ASGI server
Poetry	Latest	Dependency management
Pytest	Latest	Testing framework
Ruff	Latest	Linting & formatting

Frontend

Technology	Version	Purpose
React	18.2	UI framework
TypeScript	5.3	Type safety
Vite	5.0	Build tool
Tailwind CSS	3.4	Styling (coming soon)
Orval	Latest	API client generation
Vitest	Latest	Testing framework
Biome	Latest	Linting & formatting
React Query	Latest	Server state management (coming soon)

External Services

Service	Purpose	Status
Clerk	Authentication	Planned
Polar.sh	Billing & subscriptions	Planned
Resend	Transactional emails	Planned
Sentry	Error tracking	Planned
Vercel	Frontend hosting	Planned
Railway	Backend hosting	Planned

Infrastructure

Docker Compose: Development environment orchestration
GitHub Actions: CI/CD automation
Docker Hub: Container registry
Changesets: Version management and changelogs

Deployment

Docker Images

Production-ready Docker images are built using multi-stage builds for optimal size and security.

Build images:

# Build all images
docker compose -f docker-compose.prod.yml build

# Build specific service
docker compose -f docker-compose.prod.yml build backend

Run production containers:

docker compose -f docker-compose.prod.yml up -d

CI/CD Pipeline

The project includes automated CI/CD workflows:

Pull Request Checks: Linting, testing, type checking on every PR
Docker Build: Automated image building and pushing to registry
Deployment: Automated deployment to staging/production (coming soon)

See the CI/CD Documentation in the Starlight docs for detailed information.

Environment Variables

Production deployment requires the following environment variables:

Backend:

DATABASE_URL: PostgreSQL connection string
REDIS_URL: Redis connection string
SECRET_KEY: Application secret key
ENVIRONMENT: production

Frontend:

VITE_API_URL: Backend API URL
VITE_CLERK_PUBLISHABLE_KEY: Clerk public key (when added)

See .env.example files for complete configuration options.

Release Process

This project uses Changesets for version management and changelog generation.

Creating a Changeset

When you make changes that should trigger a release:

# Create a changeset
npm run changeset

# Follow the prompts:
# 1. Select packages to version (frontend, backend, shared)
# 2. Choose version bump type (major, minor, patch)
# 3. Write a summary of changes

Release Workflow

Development: Create changesets for your changes
Version: npm run changeset:version - Bump versions and update CHANGELOGs
Build: Test the changes
Publish: npm run changeset:publish - Publish packages (if applicable)
Git: Commit the version changes and push

Semantic Versioning

We follow Semantic Versioning:

Major (1.0.0): Breaking changes
Minor (0.1.0): New features, backward compatible
Patch (0.0.1): Bug fixes, backward compatible

Contributing

We welcome contributions! Please follow these guidelines:

Development Workflow

Fork and Clone: Fork the repository and clone to your machine
Branch: Create a feature branch (git checkout -b feat/amazing-feature)
Develop: Make your changes with proper tests
Commit: Use conventional commits (feat(backend): add amazing feature)
Test: Ensure all tests pass (npm test)
Push: Push to your fork
PR: Open a Pull Request with description

Code Standards

Linting: All code must pass linting (npm run lint)
Formatting: Use project formatters (npm run format)
Tests: Add tests for new features
Types: Maintain full type safety
Commits: Follow Conventional Commits

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes
refactor: Code refactoring
perf: Performance improvements
test: Test changes
build: Build system changes
ci: CI/CD changes
chore: Other changes

Scopes:

backend: Backend changes
frontend: Frontend changes
shared: Shared code changes
docker: Docker configuration
docs: Documentation
deps: Dependencies

Examples:

feat(backend): add user authentication endpoint
fix(frontend): resolve navigation bug on mobile
docs(readme): update installation instructions
chore(deps): upgrade FastAPI to 0.110.0

Pull Request Process

Update Documentation: Update README or docs if needed
Add Tests: Include tests for new functionality
Pass CI: Ensure all CI checks pass
Add Changeset: Create a changeset for version tracking
Request Review: Tag maintainers for review
Address Feedback: Respond to review comments
Merge: Maintainer will merge when approved

Troubleshooting

Husky Installation Errors

Ensure you ran npm install in the root directory
If hooks still don't work, try: npm run prepare
On Windows, ensure Git Bash or WSL is used

Linting/Formatting Conflicts

Run npm run lint:fix to auto-fix most issues
Check .lintstagedrc.json configuration
Biome config: frontend/biome.json
Ruff config: backend/pyproject.toml

Test Failures

Ensure all services are running: docker compose up -d
Check database migrations: docker compose exec backend alembic upgrade head
Clear test caches: cd backend && poetry run pytest --cache-clear

Docker Issues

Port conflicts: Check if ports 5173, 8000, 5432, 6379 are available
Build failures: Try clean rebuild: docker compose down -v && docker compose build --no-cache
Permission issues: On Linux, you may need to run with sudo or adjust Docker permissions

API Client Generation

Ensure backend is running: docker compose up backend
Check OpenAPI schema exports correctly: curl http://localhost:8000/openapi.json
Clear generated files: rm -rf frontend/src/api/generated
Regenerate: cd frontend && npm run generate:api

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 SaaS Starter Kit

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Technologies

FastAPI - Modern Python web framework
React - JavaScript library for user interfaces
TypeScript - Typed JavaScript
Vite - Next generation frontend tooling
Docker - Containerization platform
PostgreSQL - Advanced open source database
Redis - In-memory data structure store

Tools

Biome - Fast formatter and linter for web projects
Ruff - Extremely fast Python linter
Vitest - Blazing fast unit test framework
Pytest - Python testing framework
Orval - OpenAPI client generator
Changesets - Version management tool
Husky - Git hooks made easy

Inspiration

Built with inspiration from modern SaaS architectures and best practices in full-stack development.

Happy Coding! If you encounter any issues or have questions, please open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 115 Commits
.changeset		.changeset
.claude/commands		.claude/commands
.github		.github
.husky		.husky
.vscode		.vscode
backend		backend
docker		docker
docs		docs
done		done
frontend		frontend
shared		shared
.commitlintrc.json		.commitlintrc.json
.gitignore		.gitignore
.lintstagedrc.js		.lintstagedrc.js
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCKER_LINTING.md		DOCKER_LINTING.md
README.md		README.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
VISION.md		VISION.md
docker-compose.lint.yml		docker-compose.lint.yml
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

SaaS Starter Kit

Features

Documentation

Running the Documentation Locally

Documentation Links

Quick Start

Prerequisites

1. Clone the repository

2. Setup environment variables

3. Start with Docker Compose Watch

4. Verify everything is running

Project Structure

Development Commands

Linting & Formatting

Testing

Type Checking

Docker Commands

Running Commands Inside Containers

Database Operations

API Client Generation

Testing

Backend Testing (Pytest)

Frontend Testing (Vitest)

E2E Testing (Future)

Tech Stack

Backend

Frontend

External Services

Infrastructure

Deployment

Docker Images

CI/CD Pipeline

Environment Variables

Release Process

Creating a Changeset

Release Workflow

Semantic Versioning

Contributing

Development Workflow

Code Standards

Commit Message Format

Pull Request Process

Troubleshooting

Husky Installation Errors

Linting/Formatting Conflicts

Test Failures

Docker Issues

API Client Generation

License

Acknowledgments

Technologies

Tools

Inspiration

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages