Pearl 101 — A Beginner’s Guide

What is Pearl?

Pearl is an open ecosystem designed to make building and deploying modular applications simpler. At its core, Pearl provides a set of composable primitives that handle the repetitive plumbing — state, data flow, and integration — so you can focus on the parts of your product that matter.

Think of Pearl as a toolkit: each piece is useful on its own, but together they form a cohesive system that scales from a single script to a full production deployment.

Why Pearl?

Most ecosystems force you to learn a large framework before you can build anything useful. Pearl takes the opposite approach: start small, learn one concept at a time, and compose pieces as your needs grow.

The best way to learn Pearl is to build something with it. This guide gets you to that point as fast as possible.

Core Concepts

There are three concepts that underpin everything in Pearl. Understanding these will make the rest of the documentation intuitive.

1. Modules

A module is the basic unit of composition in Pearl. Modules are self-contained, declare their inputs and outputs, and can be combined with other modules without modification.

2. Signals

Signals are the mechanism Pearl uses to move data between modules. A signal is produced by one module and can be consumed by any number of others, creating a reactive data graph.

3. Runtimes

A runtime is the environment that executes your modules and manages signals. Pearl ships with a default runtime, but you can configure or replace it to suit your deployment target.

Your First Integration

The simplest way to get a feel for Pearl is to wire two modules together. The example below shows a module that produces a signal and a second module that reacts to it:

import { module, signal } from 'pearl'

const counter = module(() => {
  const count = signal(0)
  return { count }
})

const logger = module(({ count }) => {
  signal.watch(count, (v) => console.log('count:', v))
})

Run this in any JavaScript environment and you will see the counter’s value logged every time it changes. That is the entire mental model: modules produce signals, other modules react to them.

Next Steps

Now that you understand the building blocks, the next step is to see how they fit into the bigger picture. The Architecture guide walks through the internal design of Pearl and explains the decisions behind the system.