The Problem
Many modern web and mobile apps need real‑time, peer‑to‑peer data sync without relying on a central server. Existing cloud‑hosted databases either lock you into a vendor or lack offline‑first guarantees. Developers building decentralized or collaborative experiences therefore need a lightweight graph store that can run in browsers, Node, and native containers while handling encryption and conflict resolution.
What This Does
gun implements a decentralized graph database that replicates data over WebRTC, HTTP, or local storage. The core engine lives in the top‑level files as.js, axe.js, and browser.js; these expose the Gun constructor used by all examples.
The repository ships a large set of runnable demos under examples/ that illustrate typical usage patterns:
Angular demo – entry point examples/angular/src/main.ts and service examples/angular/src/app/gun.service.ts show how to inject a Gun instance into an Angular app. React Native demo – built from examples/react-native/package.json and native Android gradle files (examples/react-native/android/app/build.gradle). Plain HTML/JS demos – e.g., examples/basic/chat.html and examples/express.js provide quick “copy‑paste‑run” examples for browsers and Node servers.
The Dockerfile at the repository root can containerise any of these demos, and the CI definition in .github/workflows/ci.yml runs the test suite (test/.js).
How To Use It
Clone the repo git clone https://github.com/your‑fork/gun.git cd gun Install Node dependencies for the demo you need Example: Angular demo cd examples/angular npm ci # uses example_package.json; generates package-lock.json locally npm start # runs the server defined in server.js (listens on port 8080)
Example: Express demo (Node only)
cd ../.. node examples/express.js # starts an HTTP server on port 8765
If you prefer an isolated environment, build the Docker image:
docker build -t gun-demo . docker run -p 8080:8080 gun-demo # exposes the Angular demo by default
Configuration is minimal; most demos read environment variables directly from the process (e.g., process.env.PORT in examples/express.js). For production use you would replace the in‑memory adapters with a persistent storage plugin (see examples/react-native/src/extensions/asyncStorageAdapter.js for a reference implementation).
Running the test suite:
npm test # executes the 8 test files under the repository root
Real‑World Use
A SaaS platform that needs offline‑first collaboration could embed Gun in its front‑end, persisting local changes to localStorage (handled automatically by browser.js). When a user reconnects, Gun’s built‑in conflict‑resolution merges edits across peers, eliminating the need for a central sync service. The following snippet shows a typical client init:
import Gun from '../gun'; // resolves to gun.js in the repo root const gun = Gun({peers:['https://my‑relay.example.com/gun']}); gun.get('chatroom').on(msg => console.log('new message', msg));
Code Health & Issues
Low – Missing lockfile – examples/react-native/android/app/build.gradle declares Gradle dependencies without a gradle.lockfile; builds may be non‑reproducible. Low – Inconsistent package managers – Core repo lacks a package.json; demos each have their own, making unified dependency upgrades error‑prone. Medium – Sparse test coverage – Only 8 test files for a 200‑file codebase; many core modules (as.js, axe.js) are not directly exercised. Low – Legacy Bower config – Presence of bower.json suggests outdated package management; modern tooling may ignore it. Medium – Documentation gaps – README provides a high‑level intro but no explicit versioning or upgrade guide for the core library. Low – CI runs only lint/tests – No integration or end‑to‑end test for the Docker image; container builds are not validated automatically.
Overall the codebase compiles and runs the provided examples, and CI passes on the current commit.
The Bottom Line
gun delivers a functional, open‑source peer‑to‑peer graph database with extensive example code for browsers, Node, and native mobile environments. It is useful for teams that can tolerate modest test coverage and are comfortable managing multiple demo‑specific package.json files. Projects needing production‑grade stability should add lockfiles, consolidate dependencies, and expand automated testing before deployment.