Skip to main content
This quickstart guide will help you create your first GUN application with realtime synchronization in just a few minutes.
GUN is super easy to get started with. You can have a working application running in under 5 minutes!

Choose your path

You can get started with GUN in several ways:

Browser playground

Try GUN instantly in your browser with no installation

Local installation

Install GUN locally and run the examples

Quick try in browser

The fastest way to experience GUN is through the JSBin playground or the interactive tutorial. You can also view live examples at: http://try.axe.eco/

Install and run locally

1

Install GUN

Install GUN using npm:
If you don’t have Node.js or npm installed, you may need to create the node_modules directory first with mkdir node_modules, or use sudo depending on your system permissions.
2

Run the examples

Start the GUN server with examples:
This will start a relay peer server on port 8765. Visit http://localhost:8765 in your browser to see the examples.
3

Explore the examples

GUN comes with various example applications including:
  • Chat applications
  • Todo lists
  • User authentication
  • Video conferencing
  • And many more!

Build your first app

Let’s create a simple realtime application using GUN.

Step 1: Create an HTML file

Create a new file called index.html:

Step 2: Initialize GUN

Create app.js with your GUN code:

Step 3: Store and retrieve data

Add code to store and listen for data changes:
The .on() method subscribes to realtime updates. Whenever data changes, your callback function will be called automatically!

Step 4: Add realtime updates

Make the data update continuously to see realtime sync in action:

Build a todo list app

Here’s a complete example of a realtime todo list application:
Open this app in multiple browser windows or tabs to see realtime synchronization in action! Changes in one window will instantly appear in all others.

Build a chat app

Here’s a simple chat application example from the GUN repository:
You can create different chat rooms by changing the URL hash (e.g., #room1, #room2). Each hash creates a separate chat space!

Understanding GUN methods

Here are the key methods you’ll use:

.get(key)

Navigates to a node by key:

.put(data)

Stores or updates data:

.on(callback)

Subscribes to realtime updates:

.once(callback)

Fetches data once without subscribing:

.set(data)

Adds items to a set/list:

.map()

Iterates over all items in a set:
Partial updates with .put() merge with existing data. Use .put(null) to delete a property.

Connect to a relay peer

To sync data across devices, connect to a relay peer:
You can also connect to multiple peers for redundancy:

Next steps

Now that you have a basic understanding of GUN:

Installation guide

Learn about installation options for different platforms

API reference

Explore the complete GUN API

User authentication

Add user accounts with SEA (Security, Encryption, Authorization)

Examples

Explore more real-world examples