Skip to content
Legato Docs

Getting Started

Use this page to make one decision: which onboarding path to start first.

  • Contract-first
  • Capacitor runtime-first
  • Production confidence hardening

Before choosing, review Compatibility and Support Matrix to confirm supported lines and peer ranges.

Decide by risk, not by package name

Section titled “Decide by risk, not by package name”

Pick the first path based on where your integration risk lives:

  • If your main risk is shared semantics across app layers (events, snapshots, track model, invariants), start with @ddgutierrezc/legato-contract.
  • If your main risk is runtime integration with native playback surfaces (commands, media session, listeners), use @ddgutierrezc/legato-capacitor and keep @ddgutierrezc/legato-contract as the shared model.

Legato is intentionally layered: legato-contract defines shared semantics, and legato-capacitor integrates those semantics with Capacitor runtime behavior.

Decision matrix

Section titled “Decision matrix”
If you need…InstallWhy this is the fit
Shared playback events, snapshots, and invariants across multiple runtimes or app layers@ddgutierrezc/legato-contractYou can stabilize app logic first without coupling it to Capacitor runtime APIs.
Hybrid app playback with Capacitor runtime integration (audioPlayer, mediaSession)@ddgutierrezc/legato-capacitor + @ddgutierrezc/legato-contractYou need runtime commands/listeners, while still reusing the same shared contract semantics.
Rollout safety and upgrade confidence for existing integrationsUsually both packages + your app validation layerYour main risk is release behavior drift, capability assumptions, and non-explicit compatibility decisions.

Quick chooser

Section titled “Quick chooser”

Choose the first statement that is true:

  1. You are defining shared playback semantics first (types, events, invariants) -> start with @ddgutierrezc/legato-contract.
  2. You already need device/runtime controls now (play, pause, remote events, media session) -> start with @ddgutierrezc/legato-capacitor and @ddgutierrezc/legato-contract.
  3. You already run in production and your main concern is safe upgrades and confidence gates -> start with the production confidence path.

Start here

Section titled “Start here”

Contract-first

Route to the contract-first path and execute the sequence.

Capacitor runtime-first

Route to the runtime-first path and validate device playback flow.

Production confidence

Route to hardening checks before rollout or upgrade.

Then continue with Golden Paths for the prescriptive sequence.

Typical scenarios and tradeoffs

Section titled “Typical scenarios and tradeoffs”

Scenario A: Shared types first, runtime later

Section titled “Scenario A: Shared types first, runtime later”

You are aligning state, events, and queue semantics across teams before deciding runtime details.

  • Good fit: @ddgutierrezc/legato-contract
  • Tradeoff: you gain portability and testability, but runtime commands are out of scope until you add an adapter/plugin surface.

Scenario B: Hybrid app with immediate runtime needs

Section titled “Scenario B: Hybrid app with immediate runtime needs”

You already need native playback control, media-session events, and runtime capability checks.

  • Good fit: @ddgutierrezc/legato-capacitor + @ddgutierrezc/legato-contract
  • Tradeoff: faster runtime integration, but you must treat capability support as runtime-projected (not static assumptions).

Scenario C: Contract-first growth path

Section titled “Scenario C: Contract-first growth path”

You can start by making your app logic consume contract snapshots/events, then plug in Capacitor without rewriting that logic.

  • Benefit: app policy remains written against stable contract shapes.
  • Tradeoff: you need a clear boundary where runtime specifics stay in adapter/plugin-facing code.

Anti-patterns when choosing

Section titled “Anti-patterns when choosing”
  • Picking @ddgutierrezc/legato-capacitor only because “we might need native later” while no runtime integration exists yet.
  • Treating @ddgutierrezc/legato-contract as a full runtime solution; it does not provide playback execution APIs.
  • Delaying contract modeling until after runtime wiring, then retrofitting app logic to shared types under time pressure.
  • Treating finite duration as seek support; seek is capability-projected at runtime.
  • Upgrading dependencies without validating error.code, capability literals, and setup lifecycle assumptions.
Section titled “Recommended follow-up”

Golden Paths

Run a profile-based onboarding sequence with explicit outcomes.

Contract-first rationale

Understand why shared semantics come before runtime specifics.

Capability projection

Avoid static runtime assumptions when enabling controls.

Production quickstart

Validate a realistic production-oriented integration flow.

Support and community

Section titled “Support and community”