Project configuration

pyproject.toml Configuration

Below is an example configuration for an apx project. This shows the essential apx-specific settings.

[project]
name = "charming-aurora"
dynamic = ["version"]
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.119.0",
    "pydantic-settings>=2.11.0",
    "uvicorn>=0.37.0",
    "databricks-sdk>=0.74.0",
]

[tool.apx.metadata]
app-name = "charming-aurora"
app-slug = "charming_aurora"
app-entrypoint = "charming_aurora.backend.app:app"
api-prefix = "/api"
metadata-path = "src/charming_aurora/_metadata.py"

[tool.apx.ui]
root = "src/charming_aurora/ui"

[tool.apx.ui.registries]
"@animate-ui" = "https://animate-ui.com/r/{name}.json"
"@ai-elements" = "https://registry.ai-sdk.dev/{name}.json"
"@svgl" = "https://svgl.app/r/{name}.json"

Configuration Sections

`[tool.apx.metadata]`

app-name: The display name of your application
app-slug: The Python package name (snake_case)
app-entrypoint: The FastAPI application entrypoint
api-prefix: The URL prefix for API endpoints
metadata-path: Path to the generated metadata file

`[tool.apx.ui]`

root: The root directory for your UI code

`[tool.apx.ui.registries]`

Custom component registries that can be used with apx components add command. Each registry URL should contain a {name} placeholder that will be replaced with the component name.

Example:

[tool.apx.ui.registries]
"@animate-ui" = "https://animate-ui.com/r/{name}.json"

This allows you to run:

apx components add @animate-ui/fade-in

`[tool.apx.dev]`

Development server configuration options.

log_config_file: Path to an external Python logging configuration file (relative to pyproject.toml). Mutually exclusive with [tool.apx.dev.logging].

Example:

[tool.apx.dev]
log_config_file = "logging_config.py"

Inline Python logging configuration using the standard logging.dictConfig format. This configuration is merged with the default uvicorn logging setup, allowing you to add custom loggers or override specific settings while preserving the standard uvicorn logging behavior.

When you specify loggers, formatters, or handlers, they are merged with the defaults:

New entries are added
Existing entries with the same name are overridden

Example with inline tables:

[tool.apx.dev.logging]
version = 1
disable_existing_loggers = false

[tool.apx.dev.logging.formatters]
default = { format = "%(levelname)s %(name)s %(message)s" }

[tool.apx.dev.logging.handlers]
console = { class = "logging.StreamHandler", formatter = "default", stream = "ext://sys.stdout" }

[tool.apx.dev.logging.loggers]
"uvicorn" = { level = "DEBUG", handlers = ["console"], propagate = false }
"myapp"   = { level = "DEBUG", handlers = ["console"], propagate = false }

Default loggers provided by apx:

Logger	Level	Description
`uvicorn`	INFO	Main uvicorn logger
`uvicorn.error`	INFO	Uvicorn error logger
`uvicorn.access`	INFO	HTTP access logs
`{app_slug}`	DEBUG	Your application's logger

Configuration options:

version: Must be 1 (required by Python's dictConfig)
disable_existing_loggers: Whether to disable existing loggers (default: false)
formatters: Log message formatters
handlers: Output handlers (console, file, etc.)
loggers: Logger configurations by name
root: Root logger configuration

You cannot use both log_config_file and [tool.apx.dev.logging] at the same time.

`[tool.uv.workspace]`

Generated by apx init --as-member. Defines a uv workspace so multiple Python packages can share dependency resolution.

[tool.uv.workspace]
members = ["packages/*"]

members: Array of glob patterns matching workspace member directories. apx derives the glob from the member path (e.g., packages/app becomes packages/*).

See Workspaces for details.

`[dependency-groups]`

Standard Python dependency groups. apx generates a dev group with type checking tools:

[dependency-groups]
dev = [
    "ty",
]

dev: Development-only dependencies installed via uv sync. ty is the Python type checker used by apx dev check.

`[build-system]`

apx projects use hatchling as the build backend with dynamic versioning:

[build-system]
requires = ["hatchling", "uv-dynamic-versioning"]
build-backend = "hatchling.build"

`[tool.hatch]`

Hatch build configuration for wheel packaging:

[tool.hatch.version]
source = "uv-dynamic-versioning"

[tool.hatch.build]
artifacts = ["src/<app_slug>/__dist__/**"]
exclude = ["src/<app_slug>/ui"]

[tool.hatch.build.targets.wheel]
packages = ["src/<app_slug>"]

version.source: Uses uv-dynamic-versioning to derive the version from git tags
build.artifacts: Includes built frontend assets in the wheel
build.exclude: Excludes raw UI source files from the wheel (only the built __dist__ is included)
build.targets.wheel.packages: Specifies the Python package directory