Share state between different parts of the page. Named states (with beam-id) persist across server-driven updates:

`html




Add to Cart
`

Note: Named states persist when the DOM is updated by beam-action. This means reactive state is preserved even when server actions update the page.

#### JavaScript API

Access reactive state programmatically:

`javascript
// Get named state
const cartState = beam.getState("cart");
cartState.count++; // Triggers reactive updates

// Get state by element
const el = document.querySelector("[beam-state]");
const state = beam.getState(el);

// Batch multiple updates
beam.batch(() => {
state.a = 1;
state.b = 2;
});
`

#### Standalone Usage (No Beam Server)

The reactivity system can be used independently without the Beam WebSocket server:

`typescript
// Just import reactivity - no server connection needed
import "@benqoder/beam/reactivity";
`

This is useful for:

- Static sites that don't need server communication
- Adding reactivity to existing projects
- Using with other frameworks

The API is exposed on window.beamReactivity:

`javascript
// When using standalone
const state = beamReactivity.getState("my-state");
state.count++;
`

$3

Or import the included CSS (swap transitions, modal/drawer styles):

`typescript
import "@benqoder/beam/styles";
// or
import "@benqoder/beam/beam.css";
`

$3

Before (Alpine.js):

`html


`html


`html


`html


`typescript
import { createBeam } from "@benqoder/beam";

const beam = createBeam({
actions: { increment, decrement, openModal, openCart },
});
`

$3

Utility to render JSX to HTML string:

`typescript
import { render } from '@benqoder/beam'

const html = render(

`typescript
beamPlugin({
// Glob pattern for action handler files (must start with '/' for virtual modules)
actions: "/app/actions/*.tsx", // default
});
`

---

TypeScript

$3

`typescript
import type { ActionHandler, ActionResponse, BeamContext } from '@benqoder/beam'
import { render } from '@benqoder/beam'

// Action that returns HTML string
const myAction: ActionHandler = async (ctx, params) => {
return '

Add to your app/vite-env.d.ts:

`typescript
///
`

---

Examples

$3

`tsx
// actions/todos.tsx
let todos = ["Learn Beam", "Build something"];

export function addTodo(c) {
const text = c.req.query("text");
if (text) todos.push(text);
return ;
}

export function deleteTodo(c) {
const index = parseInt(c.req.query("index"));
todos.splice(index, 1);
return ;
}

function TodoList({ todos }) {
return (


{todos.map((todo, i) => (

• 
  {todo}
  beam-action="deleteTodo"
  beam-data-index={i}
  beam-target="#todos"
  >
  Delete
  
  

))}

`html


`tsx
// actions/search.tsx
export function search(c) {
const query = c.req.query("q") || "";
const results = searchDatabase(query);

return (


{results.map((item) => (

• {item.name}

))}

`html
beam-action="search"
beam-target="#results"
beam-watch="input"
beam-debounce="300"
name="q"
placeholder="Search..."
/>


`tsx
// actions/cart.tsx
let cart = [];

export function addToCart(c) {
const product = c.req.query("product");
cart.push(product);

return (
<>


`html
0

beam-action="addToCart"
beam-data-product="Widget"
beam-target="#message"
>
Add Widget



Beam provides automatic session management with a simple ctx.session API. No boilerplate middleware required.

$3

1. Enable sessions in vite.config.ts:

`typescript
beamPlugin({
actions: "/app/actions/*.tsx",
session: true, // Enable with defaults (cookie storage)
});
`

2. Add SESSION_SECRET to wrangler.toml:

`toml
[vars]
SESSION_SECRET = "your-secret-key-change-in-production"
`

3. Use in actions:

`typescript
// app/actions/cart.tsx
export async function addToCart(ctx: BeamContext, data) {
const cart = await ctx.session.get('cart') || []
cart.push({ productId: data.productId, qty: data.qty })
await ctx.session.set('cart', cart)
return
}
`

4. Use in routes:

`typescript
// app/routes/products/index.tsx
export default createRoute(async (c) => {
const { session } = c.get('beam')
const cart = await session.get('cart') || []

return c.html(



)
})
`

$3

`typescript
// Get a value (returns null if not set)
const cart = await ctx.session.get("cart");

// Set a value
await ctx.session.set("cart", [{ productId: "123", qty: 1 }]);

// Delete a value
await ctx.session.delete("cart");
`

$3

#### Cookie Storage (Default)

Session data is stored in a signed cookie. Good for small data (~4KB limit).

`typescript
beamPlugin({
session: true, // Uses cookie storage
});

// Or with custom options:
beamPlugin({
session: {
secretEnvKey: "MY_SECRET", // Default: 'SESSION_SECRET'
cookieName: "my_sid", // Default: 'beam_sid'
maxAge: 86400, // Default: 1 year (in seconds)
},
});
`

#### KV Storage (For WebSocket Actions)

Cookie storage is read-only in WebSocket context. For actions that modify session data via WebSocket, use KV storage:

`typescript
// vite.config.ts
beamPlugin({
session: { storage: "/app/session-storage.ts" },
});
`

`typescript
// app/session-storage.ts
import { KVSession } from "@benqoder/beam";

export default (sessionId: string, env: { KV: KVNamespace }) =>
new KVSession(sessionId, env.KV);
`

`toml


wrangler.toml

[vars]
SESSION_SECRET = "your-secret-key"
`

$3

`
Request comes in
↓
Read session ID from signed cookie (beam_sid)
↓
Create session adapter with sessionId + env
↓
ctx.session.get('cart') → adapter.get()
ctx.session.set('cart') → adapter.set()
`

Two components:

- Session ID: Always stored in a signed cookie (beam_sid)
- Session data: Configurable storage (cookies by default, KV optional)

$3

- Zero boilerplate - Just enable in vite.config.ts and use ctx.session
- Works in actions - Use ctx.session.get/set/delete
- Works in routes - Use c.get('beam').session.get/set/delete
- Cookie storage limit - ~4KB total size
- WebSocket limitation - Cookie storage is read-only in WebSocket (use KV for write operations)
- Signed cookies - Session ID is cryptographically signed to prevent tampering

---

Security: WebSocket Authentication

Beam uses in-band authentication to prevent Cross-Site WebSocket Hijacking (CSWSH) attacks. This is the pattern recommended by capnweb.

$3

WebSocket connections in browsers:

- Always permit cross-site connections (no CORS for WebSocket)
- Automatically send cookies with the upgrade request
- Cannot use custom headers for authentication

This means a malicious site could open a WebSocket to your server, and the browser would send your cookies, authenticating the attacker.

$3

Instead of relying on cookies, Beam requires clients to authenticate explicitly:

1. Server generates a short-lived token (embedded in same-origin page)
2. WebSocket connects unauthenticated (gets PublicApi)
3. Client calls authenticate(token) to get the full API
4. Malicious sites can't get the token (CORS blocks page requests)

$3

#### 1. Enable Sessions (Required)

The auth token is tied to sessions:

`typescript
// vite.config.ts
beamPlugin({
actions: "/app/actions/*.tsx",
session: true, // Uses env.SESSION_SECRET
});
`

#### 2. Use authMiddleware

`typescript
// app/server.ts
import { createApp } from "honox/server";
import { beam } from "virtual:beam";

const app = createApp({
init(app) {
app.use("*", beam.authMiddleware()); // Generates token
beam.init(app);
},
});

export default app;
`

#### 3. Inject Token in Layout

`tsx
// app/routes/_renderer.tsx
import { jsxRenderer } from "hono/jsx-renderer";

export default jsxRenderer((c, { children }) => {
const token = c.get("beamAuthToken");

return (





{children}

);
});
`

Or use the helper:

`tsx
import { beamTokenMeta } from "@benqoder/beam";
import { Raw } from "hono/html";



;
`

#### 4. Set Environment Variable

`bash


.dev.vars (local) or Cloudflare dashboard (production)

| Step | What Happens |
| ----------------------- | --------------------------------------------------- |
| 1. Page Load | Server generates 5-minute token, embeds in HTML |
| 2. Client Connects | WebSocket opens, gets PublicApi (unauthenticated) |
| 3. Client Authenticates | Calls publicApi.authenticate(token) |
| 4. Server Validates | Verifies signature, expiration, session match |
| 5. Server Returns | Full BeamServer API (authenticated) |

$3

| Attack | Result |
| -------------------- | -------------------------------------------------- |
| Cross-site WebSocket | Can connect, but authenticate() fails (no token) |
| Stolen token | Expires in 5 minutes, tied to session ID |
| Replay attack | Token is single-use per session |
| Token tampering | HMAC-SHA256 signature verification fails |

$3

- Algorithm: HMAC-SHA256
- Lifetime: 5 minutes (configurable)
- Payload: { sid: sessionId, uid: userId, exp: timestamp }
- Format: base64(payload).base64(signature)

$3

If you need to generate tokens outside the middleware:

`typescript
const token = await beam.generateAuthToken(ctx);
`

---

Programmatic API

Call actions directly from JavaScript using window.beam:

`javascript
// Call action with RPC only (no DOM update)
const response = await window.beam.logout();

// Call action and swap HTML into target
await window.beam.getCartBadge({}, "#cart-count");

// With swap mode
await window.beam.loadMoreProducts(
{ page: 2 },
{ target: "#products", swap: "append" },
);

// Full options object
await window.beam.addToCart(
{ productId: 123 },
{
target: "#cart-badge",
swap: "replace", // 'replace' | 'append' | 'prepend'
},
);
`

$3

`typescript
window.beam.actionName(data?, options?) → Promise

// data: Record - parameters passed to the action
// options: string | { target?: string, swap?: string }
// - string shorthand: treated as target selector
// - object: full options with target and swap mode

// ActionResponse: { html?: string | string[], script?: string, redirect?: string, target?: string }
`

$3

The API automatically handles:

- HTML swapping: If options.target is provided, swaps HTML into the target element
- Script execution: If response contains a script, executes it
- Redirects: If response contains a redirect URL, navigates to it

`javascript
// Server returns script - executed automatically
await window.beam.showNotification({ message: "Hello!" });

// Server returns redirect - navigates automatically
await window.beam.logout(); // ctx.redirect('/login')

// Server returns HTML + script - both handled
await window.beam.addToCart({ id: 42 }, "#cart-badge");
`

$3

`javascript
window.beam.showToast(message, type?) // Show toast notification
window.beam.closeModal() // Close current modal
window.beam.closeDrawer() // Close current drawer
window.beam.clearCache() // Clear action cache
window.beam.isOnline() // Check connection status
window.beam.getSession() // Get current session ID
window.beam.clearScrollState() // Clear saved scroll state
`

---

Server Redirects

Actions can trigger client-side redirects using ctx.redirect():

`typescript
// app/actions/auth.tsx
export function logout(ctx: BeamContext) {
// Clear session, etc.
return ctx.redirect("/login");
}

export function requireAuth(ctx: BeamContext) {
const user = ctx.session.get("user");
if (!user) {
return ctx.redirect("/login?next=" + encodeURIComponent(ctx.req.url));
}
// Continue with action...
}
`

The redirect is handled automatically on the client side, whether triggered via:

- Button/link click (beam-action)
- Form submission
- Programmatic call (window.beam.actionName())

---

State Preservation

$3

For pagination, users expect the back button to return them to the same page. Use beam-replace to update the URL without a full page reload:

`html
beam-action="getProducts"
beam-params='{"page": 2}'
beam-target="#product-list"
beam-replace="?page=2"
>
Page 2

`

When the user navigates away and clicks back, the browser loads the URL with ?page=2, and your page can read this to show the correct page.

`tsx
// In your route handler
const page = parseInt(c.req.query("page") || "1");
const products = await getProducts(page);
`

$3

For infinite scroll and load more, Beam automatically preserves:

- Loaded content: All items that were loaded
- Scroll position: Where the user was on the page

This happens automatically when using beam-infinite or beam-load-more. The state is stored in the browser's sessionStorage with a 30-minute TTL.

#### Infinite Scroll (auto-trigger on visibility)

`tsx


`tsx


1. User loads more content (scroll or click)
2. User navigates away (clicks a product)
3. User clicks the back button
4. Content and scroll position are restored
5. Fresh server data is applied over cached items (using beam-item-id)

#### Keeping Items Fresh with beam-item-id

When restoring from cache, the server still renders fresh Page 1 data. To sync fresh data with cached items, add beam-item-id to your list items:

`tsx



When using beam-item-id, Beam automatically handles duplicate items when appending or prepending content:

1. Duplicates are replaced: If an item with the same beam-item-id already exists, it's updated with fresh data
2. No double-insertion: The duplicate is removed from incoming HTML after updating

This is useful when:

- New items are inserted while the user is scrolling (causing offset shifts)
- Real-time updates add items that might already exist
- Race conditions between pagination requests

`html



If incoming content contains post-123 again, the existing one is updated with fresh data instead of adding a duplicate.

The action should return the new items plus the next trigger (sentinel or button):

`tsx
// app/actions/loadMore.tsx
export async function loadMoreProducts(ctx, { page }) {
const items = await getItems(page);
const hasMore = await hasMoreItems(page);

return (
<>
{items.map((item) => (

))}
{hasMore ? (
beam-load-more
beam-action="loadMoreProducts"
beam-params={JSON.stringify({ page: page + 1 })}
beam-target="#product-list"
>
Load More

) : (


No more items

`javascript
window.beam.clearScrollState();
``

This is useful when you want to force a fresh load, such as after a filter change or form submission.

---

Browser Support

Beam requires modern browsers with WebSocket support:

- Chrome 16+
- Firefox 11+
- Safari 7+
- Edge 12+

---

License

MIT