snapstack 1.0.0

The create-next-app experience for Python — zero-config FastAPI/Django/Flask scaffolding

snapstack

The create-next-app experience for Python backend projects.

Scaffold a fully wired FastAPI, Django, or Flask project in seconds -- not hours.

---

Every Python developer knows the drill: new project, 45 minutes of boilerplate. Folder structure, config, Docker, CI, tests, auth -- all wired up by hand, every single time.

JavaScript solved this years ago with create-next-app. Python didn't have an equivalent. Until now.

pip install snapstack
snapstack create my-api

Answer a few prompts. Get a production-ready project. Start coding your actual features.

---

What You Get

Every generated project includes:

• Working code on first run -- zero manual edits required
• Health check endpoint already wired and tested
• pyproject.toml with hatchling, typed config, and dev extras
• pytest test suite with fixtures and a passing test
• Dockerfile + docker-compose with multi-stage build and health checks
• GitHub Actions CI with lint + test pipeline
• JWT authentication (optional) with login, register, and refresh
• SQLAlchemy 2 / Django ORM with async support and migrations
• .env.example with documented config variables
• .pysnap.json manifest for future snapstack update upgrades

Frameworks

FastAPI Async API with Pydantic v2, SQLAlchemy 2, uvicorn snapstack create my-api \ --framework fastapi \ --db postgresql \ --auth --docker --ci

Django Classic Django with DRF, SimpleJWT, python-decouple snapstack create my-app \ --framework django \ --db postgresql \ --auth --docker --ci

Flask Minimal Flask with Blueprints, SQLAlchemy 2, factory pattern snapstack create my-service \ --framework flask \ --db sqlite \ --docker --ci

Generated Project Structure

my-api/
├── app/
│   ├── api/routes/          # Route handlers
│   ├── core/config.py       # Typed settings (.env)
│   ├── core/security.py     # JWT auth (optional)
│   ├── db/session.py        # Async database session
│   ├── models/              # ORM models
│   ├── schemas/             # Pydantic schemas
│   └── main.py              # App entrypoint
├── tests/
│   ├── conftest.py
│   └── test_health.py
├── .github/workflows/ci.yml
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── .env.example
├── .pysnap.json             # Manifest for `snapstack update`
└── README.md

Install

# Recommended
uv tool install snapstack

# Or with pip
pip install snapstack

Requires Python 3.11+.

Quick Start

Interactive mode (guided prompts)

snapstack create my-api

Non-interactive mode (CI-friendly)

snapstack create my-api \
  --framework fastapi \
  --db sqlite \
  --no-auth \
  --docker \
  --ci \
  --tests \
  --pm uv

Preview before generating

snapstack create my-api
# Shows a file tree preview before writing anything

Add features to existing projects

cd my-existing-project
snapstack add docker        # Add Dockerfile + docker-compose
snapstack add ci            # Add GitHub Actions workflow
snapstack add auth          # Add JWT authentication
snapstack add tests         # Add pytest boilerplate

Update infrastructure files

snapstack update            # Interactive diff review
snapstack update --dry-run  # See changes without applying
snapstack update --accept-all

Community templates

# Browse available templates
snapstack templates list
snapstack templates search "graphql"

Plugin System

Third-party packages can register custom framework templates via Python entry points:

# In a plugin's pyproject.toml
[project.entry-points."pysnap.plugins"]
my-template = "my_package.plugin:register"

Plugins appear automatically in prompts after pip install.

CLI Reference

Command	Description
snapstack create <name>	Scaffold a new project
snapstack add <component>	Add docker, ci, auth, or tests to existing project
snapstack update	Update infrastructure files from latest templates
snapstack templates list	List all available templates
snapstack templates search <keyword>	Search community template registry
snapstack --version	Show version

Flags for snapstack create

Flag	Values	Default
--framework, -f	fastapi, django, flask	fastapi
--db, -d	sqlite, postgresql, none	sqlite
--auth / --no-auth		--no-auth
--docker / --no-docker		--docker
--ci / --no-ci		--ci
--tests / --no-tests		--tests
--pm	uv, pip, poetry	uv
--output, -o	path	.
--no-preview		show preview
--no-validate		validate after generation

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/thewizard2030/pysnap.git
cd pysnap
pip install -e ".[dev]"
pytest

License

MIT