{"id":29436861,"url":"https://github.com/stone-foundation/stone-js-browser-adapter","last_synced_at":"2026-03-08T21:07:23.013Z","repository":{"id":240796804,"uuid":"803346043","full_name":"stone-foundation/stone-js-browser-adapter","owner":"stone-foundation","description":"Stone.js Browser adapter","archived":false,"fork":false,"pushed_at":"2025-06-12T23:24:30.000Z","size":511,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-13T00:29:48.809Z","etag":null,"topics":["context-aware","continuum-architecture","csr","javascript","official-stonejs","spa","stone-foundation","stonejs","stonejs-core","typescript"],"latest_commit_sha":null,"homepage":"https://stonejs.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stone-foundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-20T14:47:36.000Z","updated_at":"2025-06-12T23:26:36.000Z","dependencies_parsed_at":"2025-06-13T00:22:54.046Z","dependency_job_id":"7ee1bb79-48cc-4e92-be78-1342adad9f59","html_url":"https://github.com/stone-foundation/stone-js-browser-adapter","commit_stats":null,"previous_names":["stonemjs/browser-adapter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/stone-foundation/stone-js-browser-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-browser-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-browser-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-browser-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-browser-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stone-foundation","download_url":"https://codeload.github.com/stone-foundation/stone-js-browser-adapter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-browser-adapter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265091734,"owners_count":23710033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["context-aware","continuum-architecture","csr","javascript","official-stonejs","spa","stone-foundation","stonejs","stonejs-core","typescript"],"created_at":"2025-07-13T05:06:53.875Z","updated_at":"2026-03-08T21:07:22.952Z","avatar_url":"https://github.com/stone-foundation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stone.js - Browser Adapter\n\n[![npm](https://img.shields.io/npm/l/@stone-js/browser-adapter)](https://opensource.org/licenses/MIT)\n[![npm](https://img.shields.io/npm/v/@stone-js/browser-adapter)](https://www.npmjs.com/package/@stone-js/browser-adapter)\n[![npm](https://img.shields.io/npm/dm/@stone-js/browser-adapter)](https://www.npmjs.com/package/@stone-js/browser-adapter)\n![Maintenance](https://img.shields.io/maintenance/yes/2025)\n[![Build Status](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/main.yml/badge.svg)](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/main.yml)\n[![Publish Package to npmjs](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/release.yml/badge.svg)](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/release.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-browser-adapter\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-browser-adapter)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-browser-adapter\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-browser-adapter)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](./SECURITY.md)\n[![CodeQL](https://github.com/stone-foundation/stone-js-browser-adapter/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/stone-foundation/stone-js-browser-adapter/security/code-scanning)\n[![Dependabot Status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/stone-foundation/stone-js-browser-adapter/network/updates)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\nThe **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.\n\n---\n\n## Introduction\n\nIn 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.\n\nThis allows you to:\n\n* Run your full Stone.js system in the browser\n* Use the same handler and `IncomingEvent` logic as the backend\n* Handle routing, redirection, cookies, and more, entirely in the browser\n\n\u003e 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.\n\n## Installation\n\n```bash\nnpm install @stone-js/browser-adapter\n```\n\n\u003e This package is **pure ESM**. Make sure your project is ESM-compatible (`\"type\": \"module\"` in `package.json`) or configure your bundler accordingly.\n\n## Usage\n\nYou can activate the adapter either declaratively or imperatively.\n\n### Declarative API\n\n```ts\nimport { Browser } from '@stone-js/browser-adapter'\nimport { StoneApp, IncomingEvent, IEventHandler } from '@stone-js/core'\n\n@Browser()\n@StoneApp()\nexport class Application implements IEventHandler\u003cIncomingEvent\u003e {\n  handle(event: IncomingEvent): { message: string } {\n    const name = event.get\u003cstring\u003e('name', 'World')\n    return { message: `Hello ${name}!` }\n  }\n}\n```\n\n### Imperative API\n\n```ts\nimport { defineStoneApp, IncomingEvent } from '@stone-js/core'\nimport { browserAdapterBlueprint } from '@stone-js/browser-adapter'\n\nexport const handler = (event: IncomingEvent) =\u003e {\n  const name = event.get\u003cstring\u003e('name', 'World')\n  return { message: `Hello ${name}!` }\n}\n\nexport const App = defineStoneApp(handler, {}, [browserAdapterBlueprint])\n```\n\n## What It Enables\n\n* **SPA Runtime Support**\n  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.\n\n* **Route-First Event Handling**\n  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.\n\n* **Unified Cookie API**\n  You can use the same cookie methods (`getCookie()`, `setCookie()`, etc.) on both client and server, without needing browser-specific abstractions.\n\n## Configuration Options\n\nThe browser adapter supports a single configuration option:\n\n| Option   | Type       | Default                                    | Description                                       |\n| -------- | ---------- | ------------------------------------------ | ------------------------------------------------- |\n| `events` | `string[]` | `['popstate', '@stonejs/router.navigate']` | DOM or synthetic events to listen for as triggers |\n\n### Declarative Configuration\n\n```ts\n@Browser({ events: ['popstate'] })\nexport class App { /* ... */ }\n```\n\n### Imperative Configuration\n\nTo configure adapter options imperatively, use the `afterConfigure` hook:\n\n```ts\nimport { defineConfig, IBlueprint } from '@stone-js/core'\nimport { BROWSER_PLATFORM } from '@stone-js/browser-adapter'\n\nexport const AppConfig = defineConfig({\n  afterConfigure(blueprint: IBlueprint) {\n    if (blueprint.is('stone.adapter.platform', BROWSER_PLATFORM)) {\n      blueprint.add('stone.adapter.events', ['popstate'])\n    }\n  }\n})\n```\n\n\u003e Adapter selection happens at runtime. Always set configuration in `afterConfigure()` to ensure it's applied after the adapter has been resolved.\n\n## Summary\n\nThe `@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.\n\nThis adapter is a cornerstone for universal applications built with Stone.js.\n\n## API documentation\n\n* [API](https://github.com/stone-foundation/stone-js-browser-adapter/blob/main/docs)\n\n## Contributing\n\nWe welcome contributions! See the [Contributing Guide](https://github.com/stone-foundation/stone-js-browser-adapter/blob/main/CONTRIBUTING.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstone-foundation%2Fstone-js-browser-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstone-foundation%2Fstone-js-browser-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstone-foundation%2Fstone-js-browser-adapter/lists"}