Skip to content

Stability and compatibility

Evaluate package maturity, compatibility floors, release alignment, and upgrade obligations.

The workspace manifests currently use the lockstep 1.3.0-0 prerelease version. Every package remains beta or experimental; a numeric version does not imply a stable support claim.

Pin matching exact versions in controlled deployments:

{
  "dependencies": {
    "@adocommercekit/core": "1.3.0-0",
    "@adocommercekit/storefront-api": "1.3.0-0",
    "@adocommercekit/midtrans": "1.3.0-0",
    "@adocommercekit/id": "1.3.0-0",
    "@adocommercekit/biteship": "1.3.0-0"
  }
}

Upgrade every installed official package together. Confirm registry availability and release notes before copying the source-tree version into a host manifest.

Current tiers

Surface Tier Compatibility expectation
create-adocommerce Beta The project scaffolder composes official AdonisJS generation with compatible lockstep package selection; deterministic flags remain a prerelease contract.
@adocommercekit/core Beta Generic deferred/COD payment, dynamic quote, fulfillment, return, metadata, instruction, and PDP-supporting contracts are additive but not yet stable.
@adocommercekit/promotions Beta Campaign rules, coupon limits, stacking, and transactional claims remain additive prerelease contracts.
@adocommercekit/preorders Beta Preorder lifecycle, allocation, cart-processing, and backorder-policy contracts remain additive prerelease contracts.
@adocommercekit/store-credit Beta Bearer-code tender, checkout holds, ledger credits and published HTTP routes remain prerelease contracts; review money-moving changes before deployment.
@adocommercekit/engagement Beta Owned wishlists, verified-purchase review moderation and approved aggregates remain additive prerelease contracts.
@adocommercekit/storefront-api Beta The 27-endpoint baseline is host-owned; upgrade conflicts are review-only and are never overwritten.
@adocommercekit/admin-api Beta The 84-endpoint management baseline is host-owned; ability additions are minor and renames are breaking.
@adocommercekit/admin Experimental The Inertia + React panel publishes host-owned pages plus a vendored coss/Bklit UI tree; the page, primitive, and chart sets are closed lists, and the vendored registry revisions are pinned and hash-recorded per release.
@adocommercekit/stripe Beta Existing PaymentIntent behavior remains the default-inert baseline; hosts still own a complete SCA user experience.
@adocommercekit/midtrans Beta Core API v2 channels, signed notifications, expiry, and refund guidance require pinned credentials and current provider checks.
@adocommercekit/xendit Beta Payment Requests 2024-11-11 is pinned and must be revalidated before each release.
@adocommercekit/id Beta Region delivery is importer-only; tax and PDP mechanisms do not replace merchant counsel or controller duties.
@adocommercekit/biteship Beta API v1 rates and fulfillment require sandbox/production conformance for each enabled courier service.
@adocommercekit/rajaongkir Experimental Komerce API v1 rates/tracking are supported; waybill, fulfillment, COD, and insurance remain explicitly unsupported.
@adocommercekit/whatsapp Experimental Sends require approved templates, current purpose consent, a durable queue, and a host-configured fallback.
Queue adapter Experimental May change while @adonisjs/queue remains pre-1.0.

What beta means

Releases document every contract change and preserve host data, but the project has not yet claimed the adoption evidence required by its stable-release gate:

  • migration and publication changes require host review;
  • generated files can conflict with local edits and require a manual three-way merge;
  • exact behavior should be covered by the host application’s checkout and provider tests;
  • security fixes may require prompt upgrades.

Release channels

  • latest: reviewed tagged releases only.
  • beta: prerelease for the next reviewed version.
  • canary: commit-level integration packages; never use an unconstrained canary range in a deployment.

All official packages must stay on one version. Release notes should identify schema stubs, publication changes, state additions, driver contract changes, and required host actions.

The 1.3.0-0 remediation train introduces gift cards and store credit and wishlists and verified-purchase reviews. It also adds preorder deposits, promotion management, payment reconciliation, RMA/dead-letter administration, durable regional webhook/send journals, and core migrations 017–020. Existing hosts must review publication conflicts, apply migrations and map the newly used abilities before exposing these features; numeric versioning is not a production-readiness guarantee.

Upgrade policy

Whenever package versions change:

node ace commerce:upgrade
node ace migration:run
node ace commerce:doctor

Review generated files and migrations and resolve conflicts before migrating. Run the host’s complete checkout and payment smoke before deployment. Follow the upgrade procedure.

Compatibility floor

Official packages are ESM-only and require:

  • Node.js 24 or newer;
  • AdonisJS 7;
  • Lucid 22 for database-backed packages;
  • a peer dependency version allowed by each package manifest.

PostgreSQL, MySQL, and SQLite are covered by the published schema branches. The host application owns framework upgrades, database compatibility, and generated schema history.

Path to stable

A stable support-tier claim requires external use by at least two independent teams and separately documented adoption evidence. Until that evidence exists, describe packages as beta or experimental even when one integration is production-quality for a specific host.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close