Polylith Component Creation

Component Creation Skill

💡 Terminology: this skill uses Polylith terms like brick, component, namespace, and theme. If they're unfamiliar, load polylith-concepts first.

Quick command

uv run poly create component --name user_service

Command prefix: If you do not know the package manager, list lock files with ls uv.lock poetry.lock pdm.lock 2>/dev/null (a pyproject.toml is always present, so it tells you nothing on its own). Use uv run poly (uv), poetry poly (poetry), pdm run poly (pdm), hatch run poly (hatch), or poly (activated venv). Examples below use uv run.

A component is reusable, non-entry-point code (business logic, domain features, capabilities). For entry points (HTTP API, CLI, Lambda handler), use polylith-base-creation instead.

Command reference

What gets created (loose theme)

components/<namespace>/user_service/
├── __init__.py     # Public interface — empty; add re-exports here
└── core.py         # Implementation — empty; user fills it in

If [tool.polylith.test].enabled = true in workspace.toml, the CLI also creates test/components/<namespace>/user_service/test_core.py.

For the tdd theme layout (components/user_service/{src,test}/<namespace>/user_service/...), load polylith-workspace-setup.

Examples

# Minimal
uv run poly create component --name user_service

# With description
uv run poly create component --name greeting --description "Greeting domain"

Notes for the agent

• Both core.py and __init__.py are empty boilerplate. The component is not "ready" — the user fills in core.py, then re-exports its public API from __init__.py:

  # components/<namespace>/user_service/__init__.py
  from <namespace>.user_service.core import create_user, get_user
  

• Consumers import via the public interface (from <namespace>.user_service import create_user), never via core.py directly. poly deps --interface (load polylith-dependency-visualization) flags violations.
• A new component is not automatically used by any project. It is registered in a project once a base (or another component already in the project) imports it — then run poly sync (load polylith-sync).

Verification

After creation, verify the component exists using your file tools (e.g., check components/<namespace>/<name>/__init__.py). Then, you will likely need to populate core.py and __init__.py using your file writing tools since they are created empty.