Quick Start

Welcome to Happen!

Welcome to Happen, a framework for building distributed and agent-based systems founded on a philosophy of simplicity. Instead of complex abstractions, Happen provides just two fundamental building blocks, Nodes and Events, that let you create everything from simple pipelines to adaptive multi-agent ecosystems.

This guide will get you running your first multi-node Happen application in under 5 minutes.

Step 1: Prerequisites

Before you begin, make sure you have the following installed:

• Node.js (version 18+ recommended)

• Homebrew (for installing the NATS messaging server)

Step 2: Start the Messaging Backend

Happen uses the NATS messaging system as its communication backbone. The quickest way to get a NATS server running is with Homebrew. Open your terminal and run the following command:

brew install nats-server

This command starts a NATS server with JetStream (its persistence layer) enabled and makes it available to your application. You can leave this running in the background.

nats-server --js

Step 3: Get the Happen Code

Happen is currently in active development but you can download it from npm.

npm install happen-core

Step 4: Create Your First Application

Now, let's create a simple application that shows two nodes communicating. In the happen directory, create a new file named my-first-app.js and add the following code:

// Import Happen from the build output
import { initializeHappen } from 'happen-core';

// Initialize the framework. It will connect to NATS on localhost by default.
const { createNode } = initializeHappen();

// --- Create Our First Node: The Logger ---
// Nodes are independent, autonomous components.
const loggerNode = createNode('logger-service');

// This node listens for any 'greeting-was-sent' event.
loggerNode.on('greeting-was-sent', (event) => {
  console.log(`[Logger Service] Received a greeting: "${event.payload.message}"`);
});

// --- Create Our Second Node: The Greeter ---
const greeterNode = createNode('greeter-service');

// After a 1-second delay, this node will broadcast an event to the entire system.
setTimeout(() => {
  console.log('[Greeter Service] Broadcasting a greeting...');
  
  // Events are structured messages that transport data.
  greeterNode.broadcast({
    type: 'greeting-was-sent',
    payload: { message: 'Hello from the other side!' }
  });
}, 1000);

console.log('Application started. Nodes are running and listening for events...');

Step 5: Run It!

Save the file and run it from your terminal:

node my-first-app.js

You should see the following output:

Application started. Nodes are running and listening for events...
[Greeter Service] Broadcasting a greeting...
[Logger Service] Received a greeting: "Hello from the other side!"

Congratulations! You just ran your first distributed Happen application. The greeter-service node sent an event that the logger-service node received and acted upon, all without knowing anything about each other.

Next Steps

You've seen the basics of how nodes and events work. The real power of Happen comes from how these simple primitives can be combined to create resilient and complex systems.

Ready to explore more? Continue to the

Core Concepts section to deepen your understanding of the framework.