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:
npm install gun
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:
cd node_modules/gun && npm start
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: 
<!DOCTYPE html>
<html>
<head>
  <title>My First GUN App</title>
</head>
<body>
  <h1>Realtime Data</h1>
  <div id="output"></div>
  
  <script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script>
  <script src="app.js"></script>
</body>
</html>

​
Step 2: Initialize GUN

Create app.js with your GUN code: 
// GUN is already loaded via CDN
const gun = GUN();

​
Step 3: Store and retrieve data

Add code to store and listen for data changes: 
// Initialize GUN
const gun = GUN();

// Store data
gun.get('mark').put({
  name: "Mark",
  email: "[email protected]",
});

// Listen for realtime updates
gun.get('mark').on((data, key) => {
  console.log("Realtime updates:", data);
  document.getElementById('output').innerHTML = 
    `Name: ${data.name}<br>Email: ${data.email}`;
});
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: 
// Update data every second
setInterval(() => { 
  gun.get('mark').get('timestamp').put(new Date().toISOString());
}, 1000);

// Listen for timestamp updates
gun.get('mark').get('timestamp').on((data) => {
  console.log("Current time:", data);
});

​
Build a todo list app

Here’s a complete example of a realtime todo list application: 
<!DOCTYPE html>
<html>
<head>
  <title>GUN Todo List</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <h1>Thoughts</h1>
  
  <form id="form">
    <input id="input" placeholder="Add a thought...">
    <button>Add</button>
  </form>
  
  <ul id="parentList"></ul>
  
  <script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script>
  <script>
    const gun = Gun().get('thoughts');
    const parentList = document.getElementById('parentList');
    const input = document.getElementById('input');
    const form = document.getElementById('form');
    
    // Handle double-click to delete
    const dynamicEvent = e => {
      const target = e.target;
      gun.get(target.id).put(null);
      
      if (target.innerHTML === ' null' || target.innerHTML === '') {
        target.style.display = 'none';
      }
    }
    
    // Listen for all thoughts
    gun.map().on((thought, id) => {
      parentList.insertAdjacentHTML('beforeend', 
        `<li id="${id}"> ${thought}</li>`);
      
      const links = parentList.getElementsByTagName('li');
      for (const link of links) {
        if (link.innerHTML === ' null' || link.innerHTML === '') {
          link.style.display = 'none';
        } else {
          link.style.display = 'list-item';
        }
        link.ondblclick = dynamicEvent;
      }
    });
    
    // Add new thought on form submit
    form.addEventListener('submit', e => {
      e.preventDefault();
      gun.set(input.value);
      input.value = '';
    });
  </script>
</body>
</html>
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: 
<!DOCTYPE html>
<ul id='list'></ul>
<form id='form'>
  <input id='who' placeholder='name'>
  <input id='what' placeholder='say'>
  <input type='submit' value='send'>
</form>

<script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gun/axe.js"></script>
<script>
gun = GUN();
chat = gun.get("chat" + location.hash);
view = document;

// Send message on form submit
form.onsubmit = (eve) => { 
  chat.set(who.value + ': ' + what.value);
  eve.preventDefault();
  what.value = "";
}

// Display incoming messages
chat.map().on(function show(data, id){
  (view.line = view.getElementById(id) || view.createElement("li")).id = id;
  list.appendChild(view.line).innerText = data;
  window.scroll(0, list.offsetHeight);
});
</script>
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: 
gun.get('users').get('alice')

​
.put(data)

Stores or updates data: 
gun.get('user').put({ name: 'Alice', age: 25 })

​
.on(callback)

Subscribes to realtime updates: 
gun.get('user').on((data) => {
  console.log('User updated:', data)
})

​
.once(callback)

Fetches data once without subscribing: 
gun.get('user').once((data) => {
  console.log('User data:', data)
})

​
.set(data)

Adds items to a set/list: 
gun.get('todos').set({ text: 'Buy milk', done: false })

​
.map()

Iterates over all items in a set: 
gun.get('todos').map().on((todo, id) => {
  console.log('Todo:', todo)
})
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: 
const gun = GUN({
  peers: ['https://your-relay-peer.com/gun']
});
You can also connect to multiple peers for redundancy: 
const gun = GUN({
  peers: [
    'https://peer1.example.com/gun',
    'https://peer2.example.com/gun'
  ]
});

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us