Golden Paths

Use this page after choosing a path in Getting Started.

How to use this page

1. Pick one path based on your current risk surface.
2. Run the sequence in order.
3. Stop at the expected outcome.
4. Move to another path only when the level-up signal is true in your app.

Path 1: Contract-first

Choose this when

• Your first problem is semantic consistency across app layers.
• You need stable shared models for tracks, snapshots, events, errors, and capabilities.
• Runtime plugin wiring is not your immediate blocker.

Sequence

1. Read Why Contract-First to align on boundaries.
2. Read Snapshot Model to avoid nullability mistakes.
3. Implement one track using Model a Track.
4. Add typed event handling with Consume Events and Payloads.
5. Add defensive checks with Validate Runtime Invariants.

Expected outcome

You have contract-aligned app logic that can evolve independently from runtime transport details.

Level up signal

• You now need real device playback controls or media-session integration.
• Your app team is blocked by runtime behavior rather than model semantics.

Path 2: Capacitor runtime-first

Choose this when

• You already need runtime playback commands and listener wiring on device.
• You need audioPlayer and mediaSession behavior validated in a real host app.
• Your immediate risk is setup/order, queue lifecycle, and remote event handling.

Sequence

1. Start with Set Up Legato Capacitor.
2. Run Play a Track to validate queue + playback flow.
3. Add listeners with Listen to Events.
4. Add UI gating with Build Capability-Driven Controls.
5. Align local state with Use Sync Controllers.

Expected outcome

You have a runtime-integrated flow with explicit setup, event handling, and capability-gated controls.

Level up signal

• You are preparing rollout and upgrade safety checks.
• You need repeatable production confidence across app and CI.

Path 3: Production hardening

Choose this when

• You already have an integration and need safer rollout confidence.
• Your main risk is hidden assumptions during upgrades or capability handling.
• You need explicit compatibility and migration checks before production promotion.

Sequence

1. Execute Production Quickstart (Capacitor) as a baseline flow.
2. Review Compatibility and validate your package line assumptions.
3. Run Migration and Versioning checklists for your consumer profile.
4. Keep Troubleshooting open while validating error and event paths.
5. Review Releases before every upgrade rollout.

Expected outcome

You operate with explicit rollout gates: capability checks, stable literal branching, and release-aware validation.

Level up signal

• Your team can validate upgrades with clear pass/fail criteria on CI and real devices.
• Regressions are diagnosed via stable error.code and documented event/capability surfaces.

Cross-path anti-patterns

• Starting with runtime commands before agreeing on shared contract semantics.
• Treating contract types as runtime execution APIs.
• Assuming capabilities (for example seek) from media metadata instead of getCapabilities().
• Branching behavior on error.message text instead of stable error.code literals.
• Reading release notes after dependency upgrades instead of before rollout planning.

Need to re-route?

Need help choosing?

Return to the decision hub and use the quick chooser.

Contract package guide

Jump to contract documentation sections.

Capacitor package guide

Jump to Capacitor runtime documentation sections.