mirror of https://github.com/logos-messaging/js-waku.git synced 2026-01-02 13:53:12 +00:00

Arseniy Klempner 0df18b2a75

feat: create @waku/run package for local dev env (#2678 )

* feat: create @waku/run package for local dev env

* chore: add @waku/run to release please config

* feat: test @waku/run with playwright

* fix: don't run waku/run tests in CI

* fix: cache images so docker-compose can work offline

* feat: set nodekey and staticnode flags for each nwaku node

* fix: use constants for node ids

* chore: set directories for running via npx

* fix: remove .env, support env vars for nwaku ports

* fix: use separate db (same instance) for each node

* feat: add command to test dev env

* chore: use package version in container name

* fix: replace hardcoded WS/REST ports with constants/env vars

* chore: clean up README

* fix: refactor config printing into own function

* fix: add run package to release please manifest

* fix: defer to root folder gitignore/cspell

* fix: update node version and remove tsx

* fix: remove browser tests and express dep

* fix: replace magic values with constants

* fix: move to root .gitignore

* fix: move cspell to root

2025-10-22 21:38:28 -07:00

3.1 KiB

Raw Permalink Blame History

@waku/run

Spin up a local Waku network for development without relying on external infrastructure

Perfect for hackathons, offline development, or when you need a controlled testing environment for your js-waku application.

What's Included

2 nwaku nodes connected to each other with all protocols enabled:
PostgreSQL database for message persistence
Isolated network - nodes only connect to each other

Requirements

Docker Desktop or Docker Engine with Compose plugin

Quick Start

1. Start the Network

npx @waku/run start

This will:

Start 2 nwaku nodes and a PostgreSQL database
Run in the background (detached mode)
Display connection information you need for your app

Example output:

import { createLightNode } from "@waku/sdk";

const waku = await createLightNode({
  defaultBootstrap: false,
  bootstrapPeers: [
    "/ip4/127.0.0.1/tcp/60000/ws/p2p/16Uiu2HAmF6oAsd23RMAnZb3NJgxXrExxBTPMdEoih232iAZkviU2",
    "/ip4/127.0.0.1/tcp/60001/ws/p2p/16Uiu2HAm5aZU47YkiUoARqivbCXwuFPzFFXXiURAorySqAQbL6EQ"
  ],
  numPeersToUse: 2,
  libp2p: {
    filterMultiaddrs: false
  },
  networkConfig: {
    clusterId: 0,
    numShardsInCluster: 8
  }
});

2. Connect Your js-waku App

Copy the configuration from the output above and paste it into your application. Then start your node:

await waku.start();

// Your app is now connected to your local Waku network!

3. Stop When Done

npx @waku/run stop

Available Commands

Using npx (published package)

Command	Description
`npx @waku/run start`	Start the network (detached) and show connection info
`npx @waku/run stop`	Stop the network and clean up
`npx @waku/run info`	Show connection info for running network
`npx @waku/run logs`	View and follow logs from all nodes
`npx @waku/run test`	Test the network by sending a message

Configuration

All configuration is done via environment variables passed to the command.

Custom Ports

If the default ports are in use, specify custom ports:

NODE1_WS_PORT=50000 NODE2_WS_PORT=50001 npx @waku/run start

Available port configuration:

NODE1_WS_PORT (default: 60000)
NODE2_WS_PORT (default: 60001)
NODE1_REST_PORT (default: 8646)
NODE2_REST_PORT (default: 8647)

Cluster Configuration

The default configuration uses:

Cluster ID: 0
Number of shards: 8

To test with a different cluster:

CLUSTER_ID=16 npx @waku/run start

Custom nwaku Version

To use a different nwaku image version:

NWAKU_IMAGE=wakuorg/nwaku:v0.35.0 npx @waku/run start

Debugging

View Node Logs

npx @waku/run logs

Check Node Health

# Node 1
curl http://127.0.0.1:8646/health

# Node 2
curl http://127.0.0.1:8647/health

Check Peer Connections

# Node 1 debug info
curl http://127.0.0.1:8646/debug/v1/info

# Node 2 debug info
curl http://127.0.0.1:8647/debug/v1/info

License

MIT OR Apache-2.0

3.1 KiB Raw Permalink Blame History