DocsGet StartedInstallation

Installation

Package Manager

Install the TopGun client SDK and necessary adapters to get started.

terminal

npm install @topgunbuild/client @topgunbuild/adapters

Core Initialization

The most robust way to initialize TopGun is by creating the client and passing your storage adapter explicitly.

src/store.ts

import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';

// 1. Create the client — local-first by default, no server required.
//    Add `serverUrl` later when you want background sync.
const client = new TopGunClient({
  storage: new IDBAdapter(),
});

// 2. Start the client so IndexedDB initializes and queued writes can persist.
//    Non-blocking — UI renders immediately, persistence drains in the background.
client.start();

export default client;

Note: TopGunClient provides full control over configuration and lifecycle. Use this for production apps.

Server Development

Boot the server from the repository root. The default backend is embedded redb (durable, on-disk, no Postgres required); the only prerequisite is a Rust toolchain to compile the binary.

terminal

# Clone the repository
git clone https://github.com/topgunbuild/topgun.git
cd topgun

# Boot the server (auto-compiles topgun-server on first run)
pnpm start:server

# Or directly with cargo
cargo run --bin topgun-server --release

# Set an explicit port (default is 8080)
PORT=9000 pnpm start:server

No external database required. The server writes to ./topgun.redb by default; data survives restarts. Set TOPGUN_NO_AUTH=1 for auth-free local exploration. See the Server & CLI reference for flags and env vars.

Comparison

Next Section

Quickstart