flo-bit.dev
[READ-ONLY] Mirror of https://github.com/flo-bit/svelte-cloudflare-statusphere.
statusphere.atmo.tools
atproto
cloudflare-workers
oauth
svelte
add getting started
author
Florian
date
(Mar 1, 2026, 10:25 PM +0100)
commit
4b0d130c
4b0d130c13302ebdc6fa3331e4e62743a0255d2c
parent
c39e18dc
c39e18dcfb7dfd9429d72fa14b6622d82805de46
+125
-83
+122
GETTING_STARTED.md
+122
GETTING_STARTED.md
···
1
+
# Getting Started
2
+
3
+
## Prerequisites
4
+
5
+
- [Node.js](https://nodejs.org/) v18+
6
+
- [pnpm](https://pnpm.io/)
7
+
- A [Cloudflare account](https://dash.cloudflare.com/sign-up) (for production)
8
+
9
+
## Local Development
10
+
11
+
```sh
12
+
pnpm install
13
+
pnpm dev
14
+
```
15
+
16
+
That's it. In dev mode the app uses a loopback OAuth client — no keys, no Cloudflare setup, no secrets. It binds to `127.0.0.1:5183` (required for AT Protocol loopback OAuth).
17
+
18
+
Open http://127.0.0.1:5183 and log in with any Bluesky handle.
19
+
20
+
## Configure your app
21
+
22
+
Edit `src/lib/atproto/settings.ts` to set the collections your app reads/writes:
23
+
24
+
```ts
25
+
export const permissions = {
26
+
collections: ['xyz.statusphere.status'],
27
+
rpc: {},
28
+
blobs: []
29
+
} as const;
30
+
```
31
+
32
+
The OAuth scope is auto-generated from this config.
33
+
34
+
## Deploy to Production
35
+
36
+
### 1. Create KV namespaces
37
+
38
+
```sh
39
+
npx wrangler kv namespace create OAUTH_SESSIONS
40
+
npx wrangler kv namespace create OAUTH_STATES
41
+
```
42
+
43
+
Each command outputs an ID. Put them in `wrangler.jsonc`:
44
+
45
+
```jsonc
46
+
"kv_namespaces": [
47
+
{ "binding": "OAUTH_SESSIONS", "id": "<your-id>" },
48
+
{ "binding": "OAUTH_STATES", "id": "<your-id>" }
49
+
]
50
+
```
51
+
52
+
### 2. Set your public URL
53
+
54
+
In `wrangler.jsonc`, set `OAUTH_PUBLIC_URL` to your production domain:
55
+
56
+
```jsonc
57
+
"vars": {
58
+
"OAUTH_PUBLIC_URL": "https://your-domain.com"
59
+
}
60
+
```
61
+
62
+
### 3. Generate and set secrets
63
+
64
+
```sh
65
+
pnpm env:generate-key
66
+
npx wrangler secret put CLIENT_ASSERTION_KEY # paste the output
67
+
68
+
pnpm env:generate-secret
69
+
npx wrangler secret put COOKIE_SECRET # paste the output
70
+
```
71
+
72
+
### 4. Deploy
73
+
74
+
```sh
75
+
npx wrangler deploy
76
+
```
77
+
78
+
Then add a custom domain in the Cloudflare dashboard (Worker > Settings > Domains & Routes).
79
+
80
+
## Dev with tunnel (optional)
81
+
82
+
To test the full confidential client flow locally using [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
83
+
84
+
```sh
85
+
pnpm env:setup-dev # generates secrets in .env
86
+
cloudflared tunnel --url http://localhost:5183 # start tunnel (note the URL it prints)
87
+
```
88
+
89
+
Add the tunnel URL to `.env`:
90
+
91
+
```
92
+
OAUTH_PUBLIC_URL=https://your-tunnel-id.trycloudflare.com
93
+
```
94
+
95
+
Then `pnpm dev`. The app will use a confidential client with that URL.
96
+
97
+
## Scripts
98
+
99
+
| Script | Description |
100
+
|---|---|
101
+
| `pnpm dev` | Start dev server |
102
+
| `pnpm build` | Build for production |
103
+
| `pnpm check` | Run svelte-check |
104
+
| `pnpm env:generate-key` | Generate client assertion key |
105
+
| `pnpm env:generate-secret` | Generate cookie signing secret |
106
+
| `pnpm env:setup-dev` | Generate both secrets and write to `.env` |
107
+
108
+
## Optional: Profile caching
109
+
110
+
Create a KV namespace for caching Bluesky profiles (1 hour TTL):
111
+
112
+
```sh
113
+
npx wrangler kv namespace create PROFILE_CACHE
114
+
```
115
+
116
+
Add it to `wrangler.jsonc` alongside the other namespaces:
117
+
118
+
```jsonc
119
+
{ "binding": "PROFILE_CACHE", "id": "<your-id>" }
120
+
```
121
+
122
+
Without this, profiles are fetched fresh on every page load. The app works fine either way.
+3
-83
README.md
+3
-83
README.md
···
9
9
pnpm dev
10
10
```
11
11
12
-
In dev mode the app uses a **loopback OAuth client** (no keys, in-memory storage). It binds to `127.0.0.1:5183` — required for AT Protocol loopback OAuth.
13
-
14
-
### Dev with tunnel (confidential client)
15
-
16
-
To test the full production flow locally with a tunnel like [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
17
-
18
-
```sh
19
-
pnpm env:setup-dev # generates secrets in .env
20
-
# add OAUTH_PUBLIC_URL=https://your-tunnel.trycloudflare.com to .env
21
-
cloudflared tunnel --url http://localhost:5183 # start tunnel
22
-
pnpm dev # start dev server
23
-
```
24
-
25
-
## Production Deployment
26
-
27
-
### 1. Create KV namespaces
28
-
29
-
```sh
30
-
npx wrangler kv namespace create OAUTH_SESSIONS
31
-
npx wrangler kv namespace create OAUTH_STATES
32
-
```
33
-
34
-
Add the IDs to `wrangler.jsonc`:
35
-
36
-
```jsonc
37
-
"kv_namespaces": [
38
-
{ "binding": "OAUTH_SESSIONS", "id": "<your-id>" },
39
-
{ "binding": "OAUTH_STATES", "id": "<your-id>" }
40
-
]
41
-
```
42
-
43
-
### 2. Set your public URL
44
-
45
-
In `wrangler.jsonc`:
46
-
47
-
```jsonc
48
-
"vars": {
49
-
"OAUTH_PUBLIC_URL": "https://your-domain.com"
50
-
}
51
-
```
52
-
53
-
### 3. Generate and set secrets
54
-
55
-
```sh
56
-
pnpm env:generate-key
57
-
npx wrangler secret put CLIENT_ASSERTION_KEY # paste generated key
58
-
59
-
pnpm env:generate-secret
60
-
npx wrangler secret put COOKIE_SECRET # paste generated secret
61
-
```
62
-
63
-
### 4. Configure permissions
64
-
65
-
Edit `src/lib/atproto/settings.ts`:
12
+
Dev mode uses a loopback OAuth client — no keys or Cloudflare setup needed. Open http://127.0.0.1:5183 and log in with any Bluesky handle.
66
13
67
-
```ts
68
-
export const permissions = {
69
-
collections: ['xyz.statusphere.status'], // collections your app can read/write
70
-
rpc: {}, // authenticated RPC requests
71
-
blobs: [] // blob types your app can upload
72
-
} as const;
73
-
```
74
-
75
-
The OAuth scope is auto-generated from this config.
76
-
77
-
### 5. Deploy
78
-
79
-
```sh
80
-
npx wrangler deploy
81
-
```
82
-
83
-
Set up a custom domain in the Cloudflare dashboard (Worker > Settings > Domains & Routes) so the OAuth client metadata URL matches your `client_id`.
84
-
85
-
## Scripts
86
-
87
-
| Script | Description |
88
-
|---|---|
89
-
| `pnpm dev` | Start dev server |
90
-
| `pnpm build` | Build for production |
91
-
| `pnpm check` | Run svelte-check |
92
-
| `pnpm env:generate-key` | Generate client assertion key |
93
-
| `pnpm env:generate-secret` | Generate cookie signing secret |
94
-
| `pnpm env:setup-dev` | Generate both and write to `.env` |
14
+
See [GETTING_STARTED.md](GETTING_STARTED.md) for production deployment, tunnel setup, and configuration.
95
15
96
16
## Adding to an existing project
97
17
···
101
21
add atproto oauth to this project https://raw.githubusercontent.com/flo-bit/svelte-atproto-oauth-cloudflare-workers/main/AGENT_SETUP.md
102
22
```
103
23
104
-
The [agent prompt](AGENT_SETUP.md) will ask you a few questions and set everything up.
24
+
The [agent prompt](AGENT_SETUP.md) asks a few questions and sets everything up.
105
25
106
26
**Manually** — see [SETUP.md](SETUP.md) for a step-by-step guide.
107
27