bobbby.online
blonk is a radar for your web, where you follow vibes for cool blips on the radar
add starter guide
+128
+128
GETTING_STARTED.md
+128
GETTING_STARTED.md
···
1
+
# Getting Started with Blonk 📡
2
+
3
+
Welcome to Blonk! This guide will help you get your own instance running in just a few minutes.
4
+
5
+
## What You'll Need
6
+
7
+
- A computer with Node.js installed (version 18 or higher)
8
+
- A Bluesky account
9
+
- Basic familiarity with using a terminal/command line
10
+
11
+
## Step 1: Get Node.js (if you don't have it)
12
+
13
+
First, check if you have Node.js installed by opening your terminal and typing:
14
+
15
+
```bash
16
+
node --version
17
+
```
18
+
19
+
If you see a version number like `v18.x.x` or higher, you're good to go! If not, download Node.js from [nodejs.org](https://nodejs.org/) and install it.
20
+
21
+
## Step 2: Download Blonk
22
+
23
+
1. Download the Blonk code from GitHub (use the green "Code" button → "Download ZIP")
24
+
2. Unzip the file to a folder on your computer
25
+
3. Open your terminal and navigate to that folder:
26
+
27
+
```bash
28
+
cd /path/to/blonk
29
+
```
30
+
31
+
## Step 3: Install Dependencies
32
+
33
+
In your terminal, run this command to install everything Blonk needs:
34
+
35
+
```bash
36
+
npm install
37
+
```
38
+
39
+
This will take a minute or two. You'll also need to install the client dependencies:
40
+
41
+
```bash
42
+
cd client
43
+
npm install
44
+
cd ..
45
+
```
46
+
47
+
## Step 4: Set Up Your Bluesky Credentials
48
+
49
+
1. Create a new file called `.env` in the main blonk folder
50
+
2. Copy and paste this into the file:
51
+
52
+
```
53
+
BLUESKY_HANDLE=your.handle.bsky.social
54
+
BLUESKY_PASSWORD=your-app-password
55
+
```
56
+
57
+
3. Replace `your.handle.bsky.social` with your Bluesky handle
58
+
4. Replace `your-app-password` with an app password from Bluesky:
59
+
- Go to Settings → App Passwords in Bluesky
60
+
- Create a new app password
61
+
- Copy it and paste it in the .env file
62
+
63
+
⚠️ **Important**: Never share your .env file or commit it to git!
64
+
65
+
## Step 5: Start Blonk!
66
+
67
+
Run this single command to start everything:
68
+
69
+
```bash
70
+
npm run dev
71
+
```
72
+
73
+
You should see output like:
74
+
```
75
+
🚀 Blonk API server running at http://localhost:3001
76
+
➜ Local: http://localhost:5173/
77
+
```
78
+
79
+
## Step 6: Open Blonk in Your Browser
80
+
81
+
Go to http://localhost:5173/ in your web browser. You should see the Blonk interface!
82
+
83
+
## What's Next?
84
+
85
+
### Creating Your First Blip
86
+
1. Click "transmit" in the navigation
87
+
2. Enter a title and optional URL/body
88
+
3. Choose a vibe (mood-based community)
89
+
4. Click "broadcast to the radar"
90
+
91
+
### Understanding Vibes
92
+
Vibes are mood-based communities, not topic-based. Examples:
93
+
- "sunset sunglasses struts" - confident golden hour energy
94
+
- "midnight snack attack" - impulsive 2am decisions
95
+
- "cozy corner contemplation" - rainy day thoughts
96
+
97
+
### Creating New Vibes
98
+
Vibes are created virally! When someone uses a hashtag like `#vibe-your_new_vibe`:
99
+
- It needs 5 different people to use it OR
100
+
- It needs to be mentioned 10 total times
101
+
- Then it automatically becomes a real vibe!
102
+
103
+
Check the "emerging" page to see vibes that are gaining momentum.
104
+
105
+
## Troubleshooting
106
+
107
+
### "npm: command not found"
108
+
You need to install Node.js first (see Step 1)
109
+
110
+
### "Cannot find module" errors
111
+
Make sure you ran `npm install` in both the main folder and the client folder
112
+
113
+
### "Authentication failed"
114
+
Double-check your Bluesky credentials in the .env file. Make sure you're using an app password, not your main password.
115
+
116
+
### Port already in use
117
+
Another program is using port 3001 or 5173. Close other development servers or change the ports in the code.
118
+
119
+
### The page is blank
120
+
Make sure both servers are running (you should see output from both when you run `npm run dev`)
121
+
122
+
## Need Help?
123
+
124
+
- Check the logs in your terminal for error messages
125
+
- Make sure you're in the right directory when running commands
126
+
- Try stopping the server (Ctrl+C) and starting it again
127
+
128
+
Enjoy exploring the vibe-based future of social media! 🌊