Standalone engine · Vanilla JavaScript · Firebase + Firestore

Your frontend renders.
Khaya keeps it correct.

Khaya Engine is the tested layer between a vanilla JavaScript interface and Firebase. It turns user actions into serializable commands, keeps every screen synchronized, and handles confirmation, conflicts, and rollback without owning a single HTML element.

Trace one real command Build the smallest integration

Frontend: Always vanilla JavaScript
Production backend: Firebase + Cloud Firestore
Core dependencies: Zero

01 · The job

It separates interface decisions from data correctness.

A new frontend should replace its presentation without reimplementing real-time coordination. Khaya gives every vanilla frontend the same small contract: render state, execute commands, observe lifecycle.

Your frontend owns

Everything people see and touch.

HTML and semantic structure
CSS, branding, and responsive layout
Rendering and event delegation
Accessibility and interaction design

Khaya Engine owns

Everything that keeps state predictable.

Serializable state and commands
Optimistic presentation and rollback
Revisions, conflicts, and subscriptions
Lifecycle, errors, and structured events

Firebase adapter owns

Everything specific to the backend.

Firestore listeners and transactions
Firebase Authentication sessions
Offline and reconnect signals
SDK objects and transport errors

The boundary rule: DOM nodes never enter the engine. Firebase objects never enter the engine. Customer identity and project configuration never enter this repository.

02 · Architecture

Four layers. One direction of dependency.

The interface depends on the engine; the engine does not know the interface exists. Firebase stays replaceable at the code boundary even though it is Khaya's only supported production backend.

ApplicationVanilla frontendrender() · click handlers · forms

LifecycleVanilla bindingmount() · execute() · dispose()

BehaviorEngine corestate · commands · revisions · rollback

Production persistenceFirebase adapterFirestore · Auth · transactions · listeners

Down Serializable commands

Up State, status, events, errors

03 · Executable explanation

Change stock once. Follow every layer.

This safe documentation demo uses the memory adapter. The engine and binding are identical in production; the Firebase example changes only the adapter.

Frontend AOwner controls

Connecting

Frontend BCustomer view

Connecting

Under the hoodReady for a command

1
Frontend creates a commandA plain serializable object crosses the boundary.
2
Engine presents it immediatelyThe interface stays responsive while storage works.
3
Adapter commits or rejectsFirestore uses a transaction in production.
4
Every screen renders the resultThe authoritative revision flows back upward.

// Click an action to inspect its command.

Phase: Authoritative
Revision: 0
Latest event: Initial snapshot

Both frontends are independent consumers of the same engine contract.

04 · Practical guide

The smallest supported implementation.

There are only three integration decisions: create the adapter, provide a render callback, and translate interface events into commands.

Install

Add the engine and Firebase SDK.

Firebase is a peer dependency so the frontend controls its Firebase app, authentication, and project configuration.

npm install khaya-engine firebase

1
Initialize Firebase
Your application owns its dedicated project configuration.
2
Create the Firestore adapter
This is the only production persistence boundary.
3
Mount the vanilla binding
Pass state to your own renderer.
4
Execute commands from UI events
No Firebase calls belong in click handlers.
5
Dispose on teardown
The binding detaches subscriptions and listeners cleanly.

import { initializeApp } from "firebase/app"
import { getFirestore } from "firebase/firestore"
import { createRealtimeEngine } from "khaya-engine"
import { createFirebaseFirestoreAdapter }
  from "khaya-engine/firebase"
import { createVanillaBinding }
  from "khaya-engine/vanilla"

const app = initializeApp(firebaseConfig)
const adapter = createFirebaseFirestoreAdapter({
  firestore: getFirestore(app),
  initialState,
})
const engine = createRealtimeEngine({ adapter })
const binding = createVanillaBinding({
  engine,
  render(state, metadata) {
    renderCatalogue(state, metadata)
  },
})

await binding.mount()

From any click handler

Send intent, not storage instructions.

The same command drives optimistic state, the Firestore transaction, correlation events, and every subscribed frontend.

await binding.execute({
  type: "stock.adjust",
  categoryId: "catalogue",
  itemId: "coffee",
  delta: -1,
})

05 · Firebase production setup

One repeatable setup for every new frontend.

Each implementation gets isolated Firebase infrastructure. The engine code stays unchanged; only application configuration, data shape, rendering, and branding vary.

Create a dedicated Firebase project

Copy the Firebase example

Replace the public Web configuration and choose the Firestore document path.

Provision an owner

Create the Auth user and add its UID to the protected khayaEngineOwners collection.

Test Security Rules

Use the Firebase emulator to verify public reads, owner writes, revision increments, and denied access.

Build the real frontend

Replace markup and rendering while keeping the binding, adapter, and command boundary.

Open the copyable Firebase example See the minimal local example

Infrastructure stays isolated.

Never reuse another customer's Firebase project, owner UID, data, deployment target, or credentials. Firebase Web configuration belongs to the consuming frontend; service-account credentials never belong in browser code.

06 · Contract at a glance

A deliberately small public vocabulary.

Lifecyclemount()unmount()dispose()

Statesubscribe()getState()getRevision()

Commandscategory.updateitem.updateitem.additem.removestock.adjust

Signalsstatestatuseventerror

Ready for Firebase?Copy the production-path integration → Need local persistence?Inspect the browser-local starter →