https://github.com/stone-foundation/stone-js-browser-adapter
Stone.js Browser adapter
https://github.com/stone-foundation/stone-js-browser-adapter
context-aware continuum-architecture csr javascript official-stonejs spa stone-foundation stonejs stonejs-core typescript
Last synced: 3 months ago
JSON representation
Stone.js Browser adapter
- Host: GitHub
- URL: https://github.com/stone-foundation/stone-js-browser-adapter
- Owner: stone-foundation
- License: apache-2.0
- Created: 2024-05-20T14:47:36.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-12T23:24:30.000Z (about 1 year ago)
- Last Synced: 2025-06-13T00:29:48.809Z (about 1 year ago)
- Topics: context-aware, continuum-architecture, csr, javascript, official-stonejs, spa, stone-foundation, stonejs, stonejs-core, typescript
- Language: TypeScript
- Homepage: https://stonejs.dev
- Size: 499 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Stone.js - Browser Adapter
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@stone-js/browser-adapter)
[](https://www.npmjs.com/package/@stone-js/browser-adapter)
[](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/main.yml)
[](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/release.yml)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-browser-adapter)
[](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-browser-adapter)
[](./SECURITY.md)
[](https://github.com/stone-foundation/stone-js-browser-adapter/security/code-scanning)
[](https://github.com/stone-foundation/stone-js-browser-adapter/network/updates)
[](https://conventionalcommits.org)
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
```bash
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
```ts
import { Browser } from '@stone-js/browser-adapter'
import { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'
@Browser()
@StoneApp()
export class Application implements IEventHandler {
handle(event: IncomingEvent): { message: string } {
const name = event.get('name', 'World')
return { message: `Hello ${name}!` }
}
}
```
### Imperative API
```ts
import { defineStoneApp, IncomingEvent } from '@stone-js/core'
import { browserAdapterBlueprint } from '@stone-js/browser-adapter'
export const handler = (event: IncomingEvent) => {
const name = event.get('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
```ts
@Browser({ events: ['popstate'] })
export class App { /* ... */ }
```
### Imperative Configuration
To configure adapter options imperatively, use the `afterConfigure` hook:
```ts
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](https://github.com/stone-foundation/stone-js-browser-adapter/blob/main/docs)
## Contributing
We welcome contributions! See the [Contributing Guide](https://github.com/stone-foundation/stone-js-browser-adapter/blob/main/CONTRIBUTING.md) for details.