Skip to content

Commit cd114a2

Browse files
marcusreinmarcusrein
committed
update quickstart guide to streamline setup and improve clarity
1 parent bc532c3 commit cd114a2

File tree

1 file changed

+43
-119
lines changed

1 file changed

+43
-119
lines changed

‎docs/docs/quickstart.md‎

Lines changed: 43 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,77 @@
11
---
22
title: Quickstart
3-
description: Build your first Hypergraph app in minutes.
3+
description: Spin up the Hypergraph monorepo locally, including sync server, event workers, and example app.
44
version: 0.0.1
5-
tags: [quickstart, hello-world]
5+
tags: [quickstart]
66
---
77

8-
import Tabs from '@theme/Tabs';
9-
import TabItem from '@theme/TabItem';
8+
# 🚀 Quickstart
109

11-
# 🚀 Quickstart — Hello Hypergraph!
10+
Follow these steps to run the **Hypergraph monorepo** on your machine.
1211

13-
This guide walks you through spinning up a **local-first, end-to-end-encrypted Hypergraph app** with nothing but TypeScript and React.
12+
## 1. Clone the repository
1413

15-
## Requirements
16-
17-
• **Node ≥ 18** (we test on 20+)
18-
19-
• **pnpm**   `npm i -g pnpm`
20-
21-
• **Bun**   (optional, but makes the dev server blazingly fast)   `curl -fsSL https://bun.sh/install | bash`
22-
23-
---
24-
25-
## 1 — Create a project
26-
27-
We'll use **Next.js** because it supports React Server Components out of the box, but any React/TS stack works.
28-
29-
```bash title="Terminal"
30-
pnpm create next-app hello-hypergraph --ts --eslint --app --import-alias "@/*"
31-
cd hello-hypergraph
14+
```bash
15+
git clone https://github.com/graphprotocol/hypergraph.git
16+
cd hypergraph
3217
```
3318

34-
---
35-
36-
## 2 — Install the SDK
19+
## 2. Setup
3720

38-
```bash title="Terminal"
39-
# Core SDK + React helpers
40-
pnpm add @graphprotocol/hypergraph @graphprotocol/hypergraph-react
21+
Install dependencies and initialize the database:
4122

42-
# Peer deps automatically installed by pnpm, but listed here for clarity
43-
pnpm add react react-dom @automerge/automerge @automerge/automerge-repo @automerge/automerge-repo-react-hooks @tanstack/react-query effect viem
23+
```bash
24+
pnpm install
25+
cd apps/server
26+
cp .env.example .env
27+
pnpm prisma migrate dev
4428
```
4529

46-
---
47-
48-
## 3 — Run a local sync server
30+
## 3. Development
4931

50-
A sync server keeps peers in real-time sync and stores encrypted updates.
32+
Start a watcher to rebuild packages on change:
5133

52-
```bash title="Terminal"
53-
pnpm --filter server dev
34+
```bash
35+
pnpm build --watch
5436
```
5537

56-
> ✨ The server defaults to `http://localhost:3030`. Feel free to tweak `syncServerUri` later.
38+
Then, in separate terminal tabs, run the services:
5739

58-
---
40+
```bash
41+
# Terminal tab 1: event workers
42+
cd apps/events
43+
pnpm dev
5944

60-
## 4 — Wire up the provider
61-
62-
Create `src/app/providers/Hypergraph.tsx`:
45+
# Terminal tab 2: sync server
46+
cd apps/server
47+
pnpm dev
48+
```
6349

64-
```tsx title="src/app/providers/Hypergraph.tsx"
65-
'use client';
66-
import { HypergraphAppProvider } from '@graphprotocol/hypergraph-react';
50+
**Note:** Whenever you modify the Prisma schema, regenerate the client with:
6751

68-
export function Hypergraph({ children }: { children: React.ReactNode }) {
69-
// Any persistent browser storage works. LocalStorage is fine for demos.
70-
const storage = globalThis.localStorage;
71-
return (
72-
<HypergraphAppProvider storage={storage}>
73-
{children}
74-
</HypergraphAppProvider>
75-
);
76-
}
52+
```bash
53+
cd apps/server
54+
pnpm prisma migrate dev
7755
```
7856

79-
Wrap your root layout (or `_app.tsx` in pages-router) with the provider:
80-
81-
```tsx title="src/app/layout.tsx"
82-
import { Hypergraph } from '@/app/providers/Hypergraph';
83-
// ... existing imports ...
84-
85-
export default function RootLayout({ children }: { children: React.ReactNode }) {
86-
return (
87-
<html lang="en">
88-
<body>
89-
<Hypergraph>{children}</Hypergraph>
90-
</body>
91-
</html>
92-
);
93-
}
94-
```
57+
## 4. Run the Next.js example
9558

96-
---
59+
Ensure packages are built, then:
9760

98-
## 5 — Login & create a Space
99-
100-
Now let's add a very small component that:
101-
102-
1. Prompts the user to connect a wallet (using MetaMask or any EIP-1193 provider).
103-
2. Creates a new **Space** and writes a "Hello World" message into it.
104-
105-
```tsx title="src/app/page.tsx"
106-
'use client';
107-
import { useHypergraphApp } from '@graphprotocol/hypergraph-react';
108-
import { useState } from 'react';
109-
110-
export default function Page() {
111-
const { login, authenticated, createSpace } = useHypergraphApp();
112-
const [spaceId, setSpaceId] = useState<string | null>(null);
113-
114-
const onLogin = async () => {
115-
// Connect wallet via the browser provider
116-
await login(window.ethereum);
117-
};
118-
119-
const onCreate = async () => {
120-
const id = await createSpace();
121-
setSpaceId(id);
122-
};
123-
124-
return (
125-
<main className="p-8 space-y-4">
126-
{!authenticated ? (
127-
<button onClick={onLogin} className="btn">Connect Wallet</button>
128-
) : (
129-
<>
130-
<button onClick={onCreate} className="btn">Create Space</button>
131-
{spaceId && <p>✅ Created space: <code>{spaceId}</code></p>}
132-
</>
133-
)}
134-
</main>
135-
);
136-
}
61+
```bash
62+
cd apps/next-example
63+
pnpm dev
13764
```
13865

139-
> 🧩 **What just happened?**
140-
>
141-
> • `login()` stores an encrypted identity in `localStorage` and opens a WebSocket to the sync server.
142-
> • `createSpace()` generates the keys for a new Space, persists them locally, and emits a `createSpace` event to the server so other members can subscribe.
66+
Visit `http://localhost:3000` to see the example app in action.
14367

144-
---
68+
## 5. Upgrade dependencies
14569

146-
## Next steps
70+
Keep everything up to date with:
14771

148-
* Read **Core Concepts** to understand Spaces, Identities, Inboxes, and the Knowledge Graph.
149-
* Explore the **API Reference** for low-level methods and event payloads.
150-
* Open `apps/next-example` in this repo to see a more fleshed-out demo.
72+
```bash
73+
pnpm up --interactive --latest -r
74+
```
15175

15276
---
15377

0 commit comments

Comments
 (0)