Why Protostar?¶

When starting new projects, developers frequently turn to general-purpose template generators like Copier or Cookiecutter. While these tools excel at multi-language scaffolding, Protostar takes a radically different approach: deep domain specialization for the modern Python ecosystem.

If you've ever wrestled with complex Jinja conditionals just to toggle a linter, had your IDE formatters break on a templated repository, or had a template update overwrite your pyproject.toml, Protostar was engineered for you.

The Authoring Experience: TOML vs. Jinja2¶

The biggest maintenance burden in generic scaffolding engines is writing and maintaining the templates themselves. Protostar replaces brittle string templating with declarative configuration.

1. No More Broken Linters in Templates¶

In Copier, Jinja syntax ({{ variable }}) is embedded directly into source files. Because these files contain invalid syntax prior to rendering, your IDE's linters (Ruff, Black, YAML formatters) will fail or flag false positives throughout the template repository.

#:schema https://raw.githubusercontent.com/jacksonfergusondev/protostar/main/schemas/template.schema.json

name = "api-service"
description = "Production FastAPI template with Ruff and Docker"

dependencies = ["fastapi", "uvicorn[standard]", "pydantic"]
ruff = true
pytest = true
docker = true

[dev.pyproject.tool.ruff.lint]
select = ["E", "F", "I", "UP"]

# ⚠️ IDE linters and TOML formatters will break parsing this file
[project]
name = "{{ project_name }}"
dependencies = [
    "fastapi",
    "uvicorn[standard]",
    "pydantic"{% if include_database %},
    "sqlalchemy",
    "alembic"{% endif %}
]

{% if linter == "ruff" %}
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]
{% endif %}

2. Zero-Logic Templates vs. Combinatorial Explosion¶

When building templates in Copier, supporting optional features (e.g., Docker, pre-commit, direnv, multiple linters) forces the author to write deeply nested {% if %} / {% endif %} conditionals across dozens of template files. Adding even a few optional tools causes the template's complexity to explode.

# Use standard template opinions:
protostar init --template api-service

# Or override opinions on the fly without modifying the template:
protostar init --template api-service --no-docker --direnv

# copier.yml
include_docker:
  type: bool
  default: true
  help: "Include Dockerfile and compose?"
include_direnv:
  type: bool
  default: false
  help: "Include .envrc configuration?"

{# Dockerfile.jinja #}
{% if include_docker %}
FROM python:3.13-slim
...
{% endif %}

3. Built-in Domain Awareness¶

Generic templaters know nothing about Python project structures. Authors must write and maintain boilerplate files from scratch for every template:

• .gitignore matrices (ignoring .venv, __pycache__, .pytest_cache, .ruff_cache)
• Optimal multi-stage Dockerfile and .dockerignore patterns for Python
• pre-commit-config.yaml versioning and hook wiring

With Protostar, the engine is natively specialized for Python. When you toggle docker = true or ruff = true, Protostar automatically scaffolds battle-tested, best-practice artifacts without you having to write or maintain them.

4. Scalable Blueprint Distribution¶

Copier requires a complete Git repository containing a directory structure and configuration metadata. Protostar scales seamlessly across two levels:

1. The Single-File Blueprint: For lightweight environments or team standards, share a single 15-line .toml file via a GitHub Gist or URL:

   protostar init --from https://gist.githubusercontent.com/user/.../raw/backend.toml
   

2. The Multi-File Repository: For complex architectures requiring boilerplate source code (e.g., full FastAPI or PyTorch project trees), use a standard Git repository containing a protostar.toml manifest and a template/ directory with <% VARIABLE_NAME %> interpolation.

Your Experience: Safe & Deterministic¶

AST Deep-Merging vs. 3-Way Git Conflicts¶

When applying template updates or injecting tooling into an existing repository, Copier runs a 3-way Git merge against the generated file diffs. If you reformatted pyproject.toml or added custom comments, this often results in messy Git merge conflicts.

# Your existing comments and specific indentation are 100% preserved
[project]
name = "my-existing-app"
version = "0.1.0" # Version tracked in CI

[tool.ruff]
line-length = 100 # Custom setting preserved

# --- Protostar injects new tables safely ---
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

<<<<<<< HEAD
line-length = 100 # Custom setting preserved
=======
line-length = 88
>>>>>>> template/v2.0.0

Manifest-First Pre-flight Execution¶

Generic scaffolding tools execute shell hooks imperatively. If a required tool (such as uv, git, or docker) is missing from your machine, the script fails halfway through, leaving a dirty, half-scaffolded workspace.

Protostar uses a two-phase headless architecture:

1. plan() (Read-Only Phase): All modules declare requirements into a centralized EnvironmentManifest. System checks verify all dependencies upfront.
2. execute() (Side-Effect Phase): Disk mutations and subprocesses run only after the entire plan is validated.

(For a deeper visual breakdown of this two-phase execution, see Design Principles).

Comparison Matrix¶

* Cookiecutter is another popular tool in this space, but lacks native 3-way Git diff updates. Most of Copier's comparisons in this matrix apply to Cookiecutter as well.

Choosing the Right Tool¶

Next Steps¶

Ready to get started or dive deeper into the architecture?

• Getting Started: Install Protostar and scaffold your first project in seconds.
• Environment Initialization: Learn how to run Protostar interactively via the TUI wizard or headlessly via CLI flags.
• Templates & Portable Configs: Explore declarative TOML blueprints, remote templates, and dynamic variable interpolation.
• The Orchestrator: Understand the two-phase execution engine that guarantees atomicity and safe configuration merges.