framerock

minimalist framework for realtime, AI-Ready web apps

about

framerock is a lightweight framework that enables developers to build client-server JavaScript applications with minimal boilerplate. It abstracts away web server infrastructure and WebSocket management, focusing purely on the core logic of your app.

features

framerock provides a simple, secure foundation for real-time web applications. It handles the full lifecycle of a web server, including serving static resources and managing bidirectional communication via WebSocket. The framework is designed for speed, clarity, and ease of integration.

Feature	Description
Zero-dependency	Runs entirely on the Bun runtime with no external packages required
Real-time bidirectional communication	Uses raw bytes for transport, enabling full control over message format and encoding
Automatic PING/PONG	Maintains active connections with configurable timeouts and intervals
Error resilience	Wraps provided functions in try/catch blocks to prevent crashes during runtime

AI-Ready

framerock is specifically engineered to work seamlessly with AI tools and agent-based workflows. By minimizing surface area and eliminating boilerplate, it reduces context overhead and allows models to focus on application logic. This makes it ideal for iterative development, prompt engineering, and generating or reviewing agent behaviors.

Benefit	Description
Reduced context noise	LLMs receive only the relevant code and logic, not server setup or routing details
Faster iteration	Small, focused codebases enable rapid prototyping and feedback loops
Direct compatibility	Can be used as both input and output for LLMs without intermediate parsing or transformation
Safe for evaluation	Raw bytes are passed directly to backend functions, avoiding unsafe string parsing or injection risks

when to use

• when building a real-time single-page application with low-latency client-server interaction
• when you want to leverage AI tools to generate or review frontend or backend code without entangling it in web server logic
• when you need a lightweight, portable, and zero-dependency foundation for experimentation or deployment

getting started

Install framerock via Bun:

bun add 'git+https://git.daemons.my/dab/framerock.git'

Create a file named your-app-entrypoint.js with the following content:

import { async_run } from 'framerock'

await async_run({
	jsbuild_app_frontend: async function () {return `
	FRAMEROCK_UTILS.setup_transport({
		on_open: () => FRAMEROCK_UTILS.transport_send_bytes(new TextEncoder().encode('Hello from client!')),
		on_message: (event) => document.body.appendChild(document.createTextNode('Client received message: ' + new TextDecoder().decode(event.data)))
	})
	`},
	handle_transport_bytes: function (message, { client_id, transport_send_bytes }) {
		console.log(['Server received message:', client_id, new TextDecoder().decode(message)])
		transport_send_bytes(new TextEncoder().encode('Hello from server!'))
	}
})

Run the app:

bun run ./your-app-entrypoint.js

The app will start at http://127.0.0.1:8800. Open the page in a browser to see the real-time interaction between client and server.

codebase overview

file	purpose
backend/index.js	Implements the server-side logic including web server setup, route handling, WebSocket lifecycle management, and dynamic script generation
frontend/index.js	Provides client-side utility functions for managing WebSocket connections and safely executing frontend code via a custom eval wrapper

why framerock

• eliminates the need to write or maintain repetitive web server or routing code
• enables developers to focus on application logic rather than infrastructure
• supports rapid iteration and experimentation, especially when paired with AI tools
• provides a clean, transparent, and portable foundation that works across environments

changelog

• Version 1.0.0
  • page_title now defaults to "framerock app"
  • client_id now available inside handle_transport_bytes (added property to utils object)
  • ⚠️ BACKWARD-INCOMPATIBLE CHANGES ⚠️
    • handle_transport_bytes moved utils to be the final argument in function call (can be optionally consumed now)

built with framerock

• theatrics, JS Actor System with first-class support for AI Agents and Assistants