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. Initialize the storage adapter (e.g., IndexedDB)
const adapter = new IDBAdapter();

// 2. Create the client
const client = new TopGunClient({
  // Optional: URL of the sync server
  serverUrl: 'ws://localhost:3000',
  // Required: Storage adapter instance
  storage: adapter
});

// 3. Start the client (async operation)
// You typically do this in your app's entry point
await client.start();

export default client;

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

Simplified API (Experimental)

For quick prototyping, you can use the TopGun facade which abstracts some boilerplate.

src/store.ts

import { TopGun } from '@topgunbuild/client';

const db = new TopGun({
  sync: 'wss://api.myapp.com/sync',
  persist: 'indexeddb' // automatically uses IDBAdapter
});

// Note: You still need to handle the async start in a real app context

Server Development

To run the TopGun server locally for development, build and run the Rust test server binary. It uses in-memory storage with no external dependencies.

terminal

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

# Build and run the test server (requires Rust toolchain)
cargo run --bin test-server --release

# Or with a custom port
PORT=8080 cargo run --bin test-server --release

No database required for development! The test server uses in-memory storage. See the CLI Reference for details.

Comparison

Next Section

Quick Start