Stone.js - Browser Adapter

The Browser Adapter enables Stone.js to run directly in the browser, as a single-page or client-side rendered application, using the same universal interface and system design as backend deployments.

Introduction

In the Continuum Architecture, adapters are responsible for translating external context into internal system events. The browser adapter fulfills this role on the client-side by transforming browser-level navigation (like popstate or route events) into IncomingEvent objects that can be processed by your application.

This allows you to:

• Run your full Stone.js system in the browser
• Use the same handler and IncomingEvent logic as the backend
• Handle routing, redirection, cookies, and more, entirely in the browser

This adapter is runtime-focused. It does not manage DOM events or UI logic, it is designed for SPA or SSR client runtime integration, not for UI frameworks.

Installation

npm install @stone-js/browser-adapter

This package is pure ESM. Make sure your project is ESM-compatible ("type": "module" in package.json) or configure your bundler accordingly.

Usage

You can activate the adapter either declaratively or imperatively.

Declarative API

import { Browser } from '@stone-js/browser-adapter'
import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'

@Browser()
@StoneApp()
export class Application implements IEventHandler<IncomingEvent> {
  handle(event: IncomingEvent): { message: string } {
    const name = event.get<string>('name', 'World')
    return { message: `Hello ${name}!` }
  }
}

Imperative API

import { defineStoneApp, IncomingEvent } from '@stone-js/core'
import { browserAdapterBlueprint } from '@stone-js/browser-adapter'

export const handler = (event: IncomingEvent) => {
  const name = event.get<string>('name', 'World')
  return { message: `Hello ${name}!` }
}

export const App = defineStoneApp(handler, {}, [browserAdapterBlueprint])

What It Enables

• SPA Runtime Support Run your Stone.js app fully in the browser as an SPA. Routing and navigation are handled as synthetic events, passed into the system like any external request.

• Route-First Event Handling Unlike backend adapters that respond to raw HTTP requests, the browser adapter listens to high-level route events (@stonejs/router.navigate, popstate, etc.) and converts them into IncomingEvent objects.

• Unified Cookie API You can use the same cookie methods (getCookie(), setCookie(), etc.) on both client and server, without needing browser-specific abstractions.

Configuration Options

The browser adapter supports a single configuration option:

| Option | Type | Default | Description | | -------- | ---------- | ------------------------------------------ | ------------------------------------------------- | | events | string[] | ['popstate', '@stonejs/router.navigate'] | DOM or synthetic events to listen for as triggers |

Declarative Configuration

@Browser({ events: ['popstate'] })
export class App { /* ... */ }

Imperative Configuration

To configure adapter options imperatively, use the afterConfigure hook:

import { defineConfig, IBlueprint } from '@stone-js/core'
import { BROWSER_PLATFORM } from '@stone-js/browser-adapter'

export const AppConfig = defineConfig({
  afterConfigure(blueprint: IBlueprint) {
    if (blueprint.is('stone.adapter.platform', BROWSER_PLATFORM)) {
      blueprint.add('stone.adapter.events', ['popstate'])
    }
  }
})

Adapter selection happens at runtime. Always set configuration in afterConfigure() to ensure it's applied after the adapter has been resolved.

Summary

The @stone-js/browser-adapter enables Stone.js to operate in the browser with full support for routing, SPA-style execution, and context-aware event handling. It brings the same system architecture and behavior from your backend directly to the frontend, without code duplication or runtime hacks.

This adapter is a cornerstone for universal applications built with Stone.js.

API documentation

• API

Contributing

We welcome contributions! See the Contributing Guide for details.