leaflet.pub
a tool for shared writing and social publishing
awarm.space
1
2
3Leaflet is a tool for shared writing and social publishing.
4
5- **Shared writing**: make Leaflets, instant collaborative docs with rich media, multiple pages and more
6- **Social publishing**: create Publications, like blogs or newsletters, that your friends can follow — built on Bluesky
7
8## How to get started
9
10Leaflet is a fast, responsive web app — no installation needed, though you *can* add it as a PWA!
11
12TL;DR below — for more detail and examples, visit the [Leaflet Manual](https://about.leaflet.pub).
13
14### Leaflets
15
16Make a new Leaflet — a simple shareable *post* or *document* — with no account needed at [leaflet.pub/new](https://leaflet.pub/new).
17
18Use Leaflets for shared notes and docs, collections, wikis, homepages and [lots more](https://make.leaflet.pub).
19
20### Publications
21
22To make a Publication, connect with Bluesky from [leaflet.pub/home](https://leaflet.pub/home), then add posts.
23
24Use Publications on Leaflet for blogs, newsletters, project logs — anything you want people to read and follow.
25
26Read ours here: [Leaflet Lab Notes](https://lab.leaflet.pub/).
27
28### Local Development (Linux, WSL)
29
30#### Prerequisites
31
32- [NodeJS](https://nodejs.org/en) (version 20 or later)
33- [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started)
34- [Docker](https://docker.com) (required for local Supabase)
35
36#### Installation
37
381. Clone the repository `git clone https://tangled.org/leaflet.pub/leaflet.git`
39 1. If using WSL, it's recommended to install in the native file structure vs in a mounted Windows file structure (i.e, prefer installing at `~/code/leaflet` vs `/mnt/c/code/leaflet`)
402. Install the dependencies: `npm install`
413. Install the Supabase CLI:
42 - **macOS:** `brew install supabase/tap/supabase`
43 - **Windows:** `scoop bucket add supabase https://github.com/supabase/scoop-bucket.git && scoop install supabase`
44 - **Linux:** Use Homebrew or download packages from [releases page](https://github.com/supabase/cli/releases)
45 - **Via npm:** The CLI is already included in package.json, use `npx supabase` for commands
46
47#### Local Supabase Setup
48
491. Start the local Supabase stack: `npx supabase start`
50 - First run takes longer while Docker images download
51 - Once complete, you'll see connection details in the terminal output
52 - Keep note of the `API URL`, `anon key`, `service_role key`, and `DB URL`
532. Copy the `.env` file example to `.env.local` and update with your local values from the previous step:
54
55```env
56# Supabase Configuration (from `supabase start` output)
57NEXT_PUBLIC_SUPABASE_API_URL=http://localhost:54321
58NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key-from-terminal
59SUPABASE_SERVICE_ROLE_KEY=your-local-service-role-key-from-terminal
60
61# Database (default local connection)
62DB_URL=postgresql://postgres:postgres@localhost:54322/postgres
63
64# Leaflet specific
65LEAFLET_APP_PASSWORD=any-password-you-want
66
67```
68
69#### Database Migrations
70
711. Apply migrations to your local database:
72 - First time setup: `npx supabase db reset` (resets database and applies all migrations)
73 - Apply new migrations only: `npx supabase migration up` (applies unapplied migrations)
74 - Note: You don't need to link to a remote project for local development
752. Access Supabase Studio at `http://localhost:54323` to view your local database
76
77#### Running the App
78
791. `npm run dev` to start the development server
802. Visit `http://localhost:3000` in your browser
81
82#### Stopping Local Supabase
83
84- Run `npx supabase stop` to stop the local Supabase stack
85- Add `--no-backup` flag to reset the database on next start
86
87#### Feed service setup (optional)
88
89Setup instructions to run a local feed service. This step isn't necessary if you're not working on publication or BlueSky integration features.
90
911. Run `npm run start-feed-service-dev` to start the feed service with hot reloading on `http://localhost:3030`.
92
93#### Troubleshooting
94
95- Persisting articles on a fresh install over a fresh DB are usually due to stale Replicache entrys. To clear, open your browser DevTools and delete Replicache entries (usually under IndexedDB Storage)
96- Supabase settings will get cached in `.next`; if you change where you're pointing your supabase connections to you may need to delete the `.next` folder (it will rebuild next time you start the app).
97
98## Technical details
99
100The stack:
101
102- [Typescript](https://www.typescriptlang.org/) for types
103- [React](https://react.dev/) & [Next.js](https://nextjs.org/) for UI and app framework
104- [Supabase](https://supabase.com/) for db / storage layer
105- [Replicache](https://replicache.dev/) for realtime data sync layer
106- [TailwindCSS](https://tailwindcss.com/) for styling magic
107
108See the `lexicons` and `appview` directories if you're curious about our Bluesky implementation. More documentation to come; let us know if there's something you want to read about (like how to bring your own frontend using our appview!)
109
110Leaflet is open source. Please reach out by [email](mailto:contact@leaflet.pub) or [Bluesky](https://bsky.app/profile/leaflet.pub) with any questions or feedback!
111