Skip to content

ADR-0003: Optional integrations stay behind explicit extras and outside the facade

Status: accepted (2026-09-07) · Scope: all rn-forge-* packages and their optional integrations

Decision

Keep situational dependencies in named package extras. Code that needs an extra lives in the module for that capability and stays outside the base facade where importing it would require the extra; callers import that module directly. A base package remains importable with its base dependencies alone. The package manifest declares extras. Framework code generators, when built, stay in their framework codegen modules behind explicit extras and import fences.

Consequences

Consumers select capabilities through extras. Tests and documentation can name the dependency needed for each optional module, and each package's dev group self-references its extras so optional tests run instead of skipping. The unbuilt generator fences in .importlinter reserve a boundary; they do not claim that generators exist. A module whose import has a process-wide side effect, such as a library that patches the server on import, belongs behind an extra for that reason alone.

Influences

This decision shapes E1 foundation and boundaries, E6 consumer reuse, E7 Azure adapters and E11 framework code generation. ADR-0002 states where protocols and adapters live.

Alternatives considered

Making every optional SDK a base dependency would burden consumers that never use it. Re-exporting an extra-gated module from the facade would make import rn_forge.<pkg> fail without the extra.

Background

Decided 2026-09-07 as part of the root README's design principle 3; recorded here 2026-09-24. Package manifests show the current extras. Protocol placement was part of this record until 2026-09-25, when it moved to the placement rules.