BitTree – Open Source Link-in-Bio Builder (Next.js + MongoDB)

BitTree is a free, open-source Link-in-Bio builder. Claim a handle, add your links, a picture and a description, and publish a simple public profile page like https://your-domain.com/your-handle.

This project is built with the Next.js App Router and MongoDB, and is designed to be easy to clone and run locally or deploy on Vercel.

Features

• Claim a unique handle (validated server-side)
• Add multiple links with labels
• Add a profile picture URL and description
• Public profile page per handle: /[handle]
• Server-side route to persist data in MongoDB

Tech Stack

• Next.js (App Router)
• React (Client Components where needed)
• MongoDB (official Node driver)
• Tailwind CSS (utility classes in JSX)

---

Quick Start

1) Clone the repo

git clone https://github.com/your-username/bit-tree.git
cd bit-tree

2) Install dependencies

npm install
# or: pnpm install / yarn / bun

3) Configure environment variables

Create a file named .env.local in the project root and set the values as per env.sample:

MONGODB_URI="your-mongodb-connection-string"
NEXT_PUBLIC_HOST="http://localhost:3000"

Notes:

• MONGODB_URI must be a valid connection string (e.g. an Atlas URI). The app will throw an error if it’s missing.
• NEXT_PUBLIC_HOST is optional and can be your site URL in production.

4) Run the development server

npm run dev

Open http://localhost:3000 in your browser.

5) Build for production

npm run build
npm run start

---

How It Works

• Create your profile at /generate. The page is a server component that renders a client component (components/GenerateForm.js) wrapped in Suspense to safely use useSearchParams().
• When you submit, the form calls the API route POST /api/add to persist your data.
• The API handler checks if the handle already exists and returns a friendly message accordingly.
• Your public profile becomes available at /{handle}.

Key files:

• app/generate/page.js – server component page + metadata
• components/GenerateForm.js – client UI and logic
• app/api/add/route.js – API endpoint to insert new records
• lib/mongodb.js – MongoDB client connection helper

---

Environment & Configuration

See env.sample for required variables. In summary:

• MONGODB_URI – required. MongoDB connection string
• NEXT_PUBLIC_HOST – optional. Your site base URL

lib/mongodb.js will throw if MONGODB_URI is not provided.

---

API

POST /api/add

Body (JSON):

{
  "handle": "johndoe",
  "links": [{ "link": "https://x.com/john", "linktext": "X" }],
  "picture": "https://.../avatar.jpg",
  "description": "Hello, I build things."
}

Responses:

• Success: {"success": true, "message": "🌳 Your Bittree was created successfully! 🎉"}
• Handle taken: {"success": false, "message": "🚫 Handle is already taken, try another one ✨"}

---

Deploy

The recommended way to deploy is with Vercel.

1. Push your repository to GitHub/GitLab/Bitbucket
2. Import the project in Vercel
3. Set the Environment Variables in Vercel Project Settings:
   • MONGODB_URI
   • NEXT_PUBLIC_HOST (your production URL)
4. Deploy

MongoDB: You can use MongoDB Atlas (free tier). Create a cluster and copy the connection string as MONGODB_URI.

---

Project Structure (excerpt)

app/
  [handle]/page.js         # Public profile page
  api/add/route.js         # API to create BitTree entries
  generate/page.js         # Generate page (server) + metadata
components/
  GenerateForm.js          # Client form UI/logic
  Navbar.js
lib/
  mongodb.js               # MongoDB connection helper
public/
  ...

---

Contributing

Contributions are welcome! Please open an issue or submit a PR. For larger changes, consider creating a discussion first.

Development tips

• Keep server and client responsibilities separated (server components vs client components)
• Prefer relative API routes in the browser (e.g., fetch('/api/add'))
• Ensure MONGODB_URI is available locally and in deployment

---

License

This project is free and open source under the MIT License.

---

Acknowledgements

• Built with Next.js
• Deployed easily with Vercel
• Database by MongoDB Atlas