Local Kyma Development for Commerce Extensions: Mocks, Wiring, and the Fast Loop

The event-driven extensions guide covers what to build on Kyma: functions and microservices consuming commerce events and calling back through OCC and Integration APIs. This guide covers where to build it before anything reaches a shared environment, because the difference between a two-minute and a two-hour feedback loop decides whether side-by-side extensibility actually gets adopted by your team. The CX Works generation of this material was written for Kyma 1.x on Minikube with the Varkes mock framework; the tooling has moved on, the architecture of a good local loop has not. Both are below.

The Three Local Setups, Cheapest First#

1. Mock-only (the default). You do not need a running SAP Commerce at all to develop most extensions. The commerce application mock pattern (SAP has published mock applications exposing commerce-shaped OCC APIs and emitting commerce events; the historical home was the xf-application-mocks repository, with successors among the SAP samples for Kyma runtime extensions) registers itself against your Kyma cluster exactly like a real commerce instance: same event catalog, same API metadata. Your function development loop becomes: trigger a simulated order.created from the mock's cockpit, watch your function fire, iterate. This is the loop for 80% of extension work, and it runs on a laptop.

2. Local Kyma cluster. The Kyma CLI provisions a local cluster on k3d (the modern replacement for the Minikube instructions in older material): a Kubernetes-in-Docker cluster with the Kyma modules you enable. Local Kyma plus the mock is a fully offline extension lab. Check the current Kyma CLI documentation for the provisioning invocation of your version; the module system (post-2.x Kyma) means you enable eventing, serverless, and the application connectivity pieces you need rather than installing a monolith.

3. Local commerce paired with local Kyma (the full rig). Needed only when your extension depends on customizations the mock cannot fake (custom events, custom OCC endpoints, your Integration Objects). This is the setup the original CX Works article documented, and its two challenges are timeless enough to keep on record, because they resurface in any self-signed, two-local-systems pairing:

• DNS from inside the cluster: Kyma pods must reach your host machine's commerce instance. The classic trick is the cluster's route to the host (ip route show from inside the cluster VM/container) plus a wildcard-DNS name that embeds the IP, historically via nip.io, wired into the commerce property that advertises its own API URL (ccv2.services.api.url.0 in the API registry configuration), plus apiregistryservices.events.exporting=true so events actually leave the building.
• Mutual trust between two self-signed parties: the Kyma application connector expects TLS with client authentication; local commerce presents a self-signed certificate. On the commerce side, the platform's additional developer trust store is the sanctioned hook (additional.javax.net.ssl.trustStore pointing at the shipped ydevelopers.jks, with kymaintegrationservices.truststore.* aimed at the same file), into which you import the local Kyma CA. On the Kyma side, local development historically required relaxing verification on the application registry and gateway (insecure-spec-download and skip-verify flags patched onto the deployments). Every one of those switches is a local-only concession; the moment configuration like that appears in anything shared, you have a security finding, not a dev environment.

The one-click integration flow (commerce registering its events and APIs with the paired Kyma application) then behaves exactly as against a cloud instance, which is the point: the local rig exists to make the registration, catalog, and consumption mechanics boring before they meet a shared environment.

The Loop Itself#

Whatever setup tier you run, the productive loop looks the same:

1. Contract first: pin the event type and payload (from the commerce event catalog or your custom event definition) and the API calls your extension makes. Write them down as the function's README before code exists; this is also your mock configuration.
2. Function locally, dependencies faked: serverless functions are plain code; run them as such with a stub event payload in a unit test harness before they ever deploy to a cluster. The cluster is for integration behavior (triggers, bindings, scaling), not for your business logic's first draft.
3. Deploy to local Kyma, drive with the mock: emit events from the mock cockpit, assert side effects. This is where binding mistakes, payload-shape surprises, and auth wiring die cheaply.
4. Promote to a dev cluster against a dev commerce: only contracts already proven locally. What you are validating here is environment configuration (real credentials, real event volumes, real network policy), not logic.

The discipline that makes this work is the same consumer-driven-contract thinking as the OCC contract guide: the mock is only as good as its fidelity to the real payloads, so when a real environment teaches you a payload surprise, the fix lands in the mock configuration and a contract test, not just in the function.

What Changed Since the Source Era, Honestly#

• Minikube to k3d: local Kyma provisioning moved; the concept (disposable local cluster, CLI-provisioned) is identical.
• Varkes: the mock framework from the incubator era is effectively historical; the mock pattern it implemented (a lightweight server presenting OpenAPI/OData specs plus an event trigger UI, registered via the application connector) lives on in the maintained sample mocks. If you need to mock your own custom surface, a small Node or Java service implementing your OpenAPI spec plus the connector registration achieves what Varkes packaged.
• Kyma's own architecture: eventing and connectivity internals have been rebuilt across Kyma 2.x; treat any tutorial's kubectl patches and component names as version-specific, and the reasons for them (trust, DNS, event export) as the stable knowledge.
• The commerce side is the stable half: the API registry properties, the developer trust store, the event export switch, and the one-click integration have been consistent for years. When the pairing breaks, debug the Kyma side first and the commerce properties second; that ordering wins on base rates.

Checklist#

• Team default is mock-first development; a laptop with no commerce install can build and test a standard-event extension
• Local cluster provisioning documented for the Kyma version in use (one page, tested quarterly, because CLI flags rot)
• Custom events and Integration Objects have mock definitions maintained alongside their real definitions
• The full local rig (local commerce paired with local Kyma) documented with its trust and DNS steps, and explicitly marked local-only
• Contract tests pin event payloads and OCC responses; mock fidelity failures feed back into the mocks
• Promotion path (local, dev cluster, stage) defined with what each tier is allowed to catch

Side-by-side extensibility earns its keep when the marginal extension is cheap: an idea on Monday, a function consuming order.created by Tuesday, in front of stakeholders by Friday. That economy is created almost entirely by the quality of the local loop, which costs a few days to set up once and pays on every extension after.