🌐 LinkGrid

A Modern Self-Hosted Link-in-Bio Platform

Beautiful • Fast • Full Control

Live Demo • Report Bug • Request Feature

📖 Table of Contents

What is LinkGrid?
Feature Highlights
LinkGrid vs Competitors
Screenshots
Quick Start
Initial Setup
Managing Links
Cloud Storage (Optional)
Analytics Dashboard
Security
Project Structure
Deployment
System Architecture
Performance Philosophy
Roadmap
Extending LinkGrid
Important Notes
Contributing
License
Support
Contact

🚀 What is LinkGrid?

LinkGrid is a fully self-hosted, production-ready alternative to commercial link-in-bio platforms like Linktree and Bio.link.

Designed for:

👨‍💻 Developers — Full backend control and customization
🎨 Creators — Beautiful themes without coding
🏢 Agencies — White-label solution for clients
🔒 Privacy-focused users — Your data stays yours
💼 SaaS builders — Foundation for link management products

You Own:

✅ Your data
✅ Your analytics
✅ Your hosting
✅ Your infrastructure

No third-party tracking. No recurring fees. No vendor lock-in.

✨ Feature Highlights

Feature	Description
🎨 5 Built-in Themes	Minimal, Cyber, Glass, Terminal, Elegant
⚙️ Web-Based Settings	Configure everything from `/settings` page — no code needed
📊 Built-in Analytics	Track clicks, countries, devices, and hourly activity from `/admin`
🔍 Live Search	Instant filtering with result count
🖱️ Dedicated Links Manager	Separate protected page (`/links`) for full CRUD and drag & drop
🖼️ Automatic Favicons	Icons are fetched automatically from websites
🔐 Secure Authentication	Passwords hashed with bcrypt, session-based login
☁️ Cloud Storage Ready	Use JSONbin.io for persistent data on ephemeral platforms
🚀 Blazing Fast	Pure vanilla JS, no heavy frameworks
📱 Fully Responsive	Looks perfect on any device
♿ Accessibility Ready	Respects `prefers-reduced-motion`, keyboard navigation
🔓 MIT Licensed	Free for personal and commercial use

🆚 LinkGrid vs Competitors

Comparison with Other Platforms

Feature	LinkGrid	Linktree	Bio.link	Carrd
Hosting Model	✅ Self-hosted	❌ SaaS only	❌ SaaS only	❌ Hosted platform
Data Ownership	✅ Full control	⚠️ Platform-owned	⚠️ Platform-owned	⚠️ Platform-owned
Analytics	✅ Self-controlled	📊 Third-party scripts	📊 Platform analytics	📊 Limited (paid)
Customization	✅ Full CSS control	🎨 Template-based	🎨 Basic only	🎨 Flexible (complex)
Backend Access	✅ Full access	❌ No access	❌ No access	❌ No access
Performance	⚡ Lightweight	⚠️ External scripts	⚠️ External scripts	⚠️ Varies
Pricing	💸 Free (MIT)	💸 Freemium	💸 Freemium	💸 Paid plans
Branding	🚫 None	⚠️ Free tier branding	⚠️ Free tier branding	⚠️ Free tier branding
Open Source	✅ Yes	❌ No	❌ No	❌ No
Monthly Fees	✅ None	❌ Yes	❌ Yes	❌ Yes

Key Advantages

Full Backend Control — Extend, modify, and customize everything
Own Your Analytics — No external tracking scripts
No SaaS Lock-in — Export your data anytime
Privacy-First — Your data never leaves your server
Developer-Friendly — Clean codebase, easy to extend

📸 Screenshots

🌙 Elegant Theme (Default)

🎨 Themes Preview

Minimal	Cyber	Glass	Terminal

🖥️ Admin Interface

Settings Page	Analytics Dashboard	Links Manager	Live Search

Note: The new dedicated /links page provides a clean, protected interface for managing your links, separate from the public view.

🚀 Quick Start

📦 Installation

Requirements: Node.js 18+

# Clone the repository
git clone https://github.com/VEX-SL/linkgrid.git

# Navigate to directory
cd linkgrid

# Install dependencies
npm install

# Start the server
npm start

Access your site: Open http://localhost:3000

⚙️ Initial Setup

🔐 First Login

Navigate to http://localhost:3000/admin (or any protected page)
Login with the default password: admin
⚠️ CRITICAL: Change your password immediately from the settings page!

🎨 Configure Your Profile

Visit http://localhost:3000/settings to customize:

Theme — Choose from 5 beautiful themes
Profile Photo — Upload your picture
Name & Bio — Your personal information
Footer Text — Customize the footer
Search — Enable/disable live search
Password — Change your admin password

Everything is managed from the web interface — no coding required!

🖱️ Managing Links (Admin Interface)

LinkGrid now features a dedicated, protected page for link management: /links.

Accessing the Links Manager

Go to http://your-site.com/links
Log in with your admin password (shared across /admin, /settings, /links)

Features of `/links` Page

✅ Full CRUD — Create, read, update, delete links
✅ Drag & Drop — Reorder links instantly with visual feedback
✅ Automatic Favicons — See icons as you type "auto"
✅ Admin-style UI — Dark theme consistent with /admin and /settings
✅ Separate from public view — No risk of accidental edits while visitors browse

☁️ Cloud Storage (Optional)

If you deploy on platforms with ephemeral storage (like Replit, Glitch, etc.), you must use JSONbin.io to persist your data permanently.

📋 JSONbin.io Setup

We've created a dedicated page that contains all the JSON code you need — ready to copy & paste.

👉 Visit the preparation page: https://links--vex-sl.replit.app/prepare

This page includes:

✅ The exact JSON for Settings, Links, and Statistics bins
✅ Step-by-step instructions for creating bins on JSONbin.io
✅ Copy buttons for each JSON block (no manual typing!)
✅ All required environment variables explained

Quick Setup Steps:

Create a free account at jsonbin.io
Get your API Key from the dashboard
Use our prep page to copy and create three bins:
- Settings bin — paste the settings JSON
- Links bin — paste the links JSON
- Statistics bin — paste the empty stats structure
Copy each bin's ID

Environment Variables

Create a .env file (or set environment variables in your hosting platform):

NODE_ENV=production
SESSION_SECRET=your-strong-random-string-64-chars
JSONBIN_KEY=your-jsonbin-master-key
SETTINGS_BIN_ID=your-settings-bin-id
LINKS_BIN_ID=your-links-bin-id
STATS_BIN_ID=your-stats-bin-id

The app will automatically use JSONbin for all data storage if these variables are set.

📊 Analytics Dashboard

Visit /admin to see:

✅ Total clicks across all links
📈 Per-link statistics with last click time
🌍 Top countries where your visitors are from
📱 Device breakdown (Desktop, Mobile, Tablet)
⏰ Hourly activity chart

All analytics are stored locally (or in JSONbin) — no third-party tracking services!

🔒 Security

Password Management

Default password: admin

⚠️ CRITICAL: Change the default password immediately after first login!

To Change Your Password:

Go to /settings
Enter your new password in the "Admin Password" field
Save

The password is hashed using bcrypt before storage.

Forgot Your Password?

If you forget your password, you can:

Check your JSONbin settings bin (if using cloud storage)
Or reset it manually in public/data/settings.json (local storage)
After reset, go to /settings and set a new password

Security Best Practices:

✅ Use a strong, unique password
✅ Enable HTTPS in production
✅ Don't share your admin links publicly
✅ Regularly backup your data
✅ Set SESSION_SECRET to a long random string

📁 Project Structure

linkgrid/
├── index.js                # Express server (backend)
├── package.json            # Node.js dependencies
├── public/
│   ├── index.html          # Main public page
│   ├── admin.html          # Analytics dashboard
│   ├── settings.html       # Settings page
│   ├── admin-links.html    # Dedicated links manager page
│   ├── prepare.html        # Prep page for JSONbin setup
│   ├── style.css           # All themes & styles
│   ├── script.js           # Frontend logic
│   ├── profile.jpg         # Your profile photo
│   ├── favicon.png         # Site favicon
│   └── data/               # Local storage (when not using JSONbin)
│       ├── settings.json
│       ├── links.json
│       └── statistics.json
└── screenshots/            # For README

🌐 Deployment

Cloud Platforms (Railway / Render / Heroku)

Push your repository to GitHub
Connect to your platform (Railway/Render/Heroku)
Set environment variables as needed
Set start command: node index.js
Done! 🎉

For ephemeral platforms (Replit, Glitch, etc.) — must use JSONbin.io for persistent storage.

VPS / Self-Hosted (Recommended)

Using PM2 for Process Management:

# Install PM2 globally
npm install -g pm2

# Start LinkGrid with PM2
pm2 start index.js --name linkgrid

# Save PM2 configuration
pm2 save

# Setup PM2 to start on system boot
pm2 startup

Recommended Production Setup:

✅ NGINX reverse proxy
✅ HTTPS (Let's Encrypt)
✅ Firewall rules
✅ Regular backups of public/data/

🏗️ System Architecture

For Developers: Technical deep-dive into how LinkGrid works.

Frontend Layer

Pure Stack: HTML / CSS / JavaScript (Vanilla, no frameworks)
Theming: CSS Variables — all themes defined in style.css
Dynamic Rendering: index.html fetches data via JavaScript
Favicon Auto-fetch: Icons are automatically fetched from icons.duckduckgo.com
Live Search: Real-time filtering of links
Drag & Drop: Implemented with SortableJS

Backend Layer

Server: Node.js + Express
Storage: JSON files (local) OR JSONbin.io (cloud)
Analytics Pipeline:
1. User clicks a link
2. Frontend sends POST /api/click
3. Server extracts IP, geolocation (via ip-api.com + geoip-lite), device type
4. Server updates statistics (local file or JSONbin)
Admin Authentication: Session-based using express-session with bcrypt password hashing

Environment Variables:

NODE_ENV — production or development
SESSION_SECRET — secret for session encryption
JSONBIN_KEY, *_BIN_ID — for cloud storage

Data Flow (Local Storage)

┌─────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   Browser   │  ───► │   Express API   │  ───► │   JSON Files    │
│(index.html) │       │   (index.js)    │       │ (public/data/)  │
└─────────────┘       └─────────────────┘       └─────────────────┘
       ▲                                                   │
       └───────────────────────────────────────────────────┘
                        (static files)

Data Flow (Cloud Storage)

┌─────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   Browser   │  ───► │   Express API   │  ───► │   JSONbin.io    │
│(index.html) │       │   (index.js)    │       │  (Cloud API)    │
└─────────────┘       └─────────────────┘       └─────────────────┘
       ▲                                                   │
       └───────────────────────────────────────────────────┘
                        (static files)

Design Principles

⚡ Minimal dependencies — No heavy frameworks
🚀 High performance — Lightweight runtime
🔧 Easy extensibility — Clean, modular code
📊 Transparent data flow — Simple to understand and modify

📈 Performance Philosophy

LinkGrid is designed for speed and efficiency:

⚡ Lightweight runtime
📦 No heavy framework bundles
💾 Minimal memory footprint
🚀 Fast initial paint
⚙️ Efficient event handling

Scales vertically — Perfect for VPS deployment.

🛣️ Roadmap

✅ Completed Features

🚧 Planned Features

🧩 Extending LinkGrid

For Developers: LinkGrid is designed for modification. You can:

🔄 Replace JSON storage with a database
🎨 Create custom themes
🔌 Add middleware
📊 Build custom analytics dashboards
🌐 Integrate external APIs

Developer-first architecture — easy to extend and customize.

⚠️ Important Notes

Change Default Password: The default password is admin — change it immediately from /settings!
Privacy Compliance: The analytics system records IP addresses (to determine country). Be aware of privacy regulations (GDPR, CCPA).
Backup Your Data: Regularly backup your data:
- Local storage: public/data/ folder
- Cloud storage: JSONbin.io dashboard
HTTPS in Production: Always use HTTPS when deploying publicly to protect your admin password and session cookies.
Ephemeral Storage Platforms: If deploying on Replit, Glitch, etc., you must use JSONbin.io for persistent data — otherwise all data will be lost on restart.
Environment Variables: Never commit .env file to Git. Use your hosting platform's secret management.
Use Our Prep Page: For quick JSONbin setup, visit https://links--vex-sl.replit.app/prepare — it contains all the code you need to copy.
No More AdminPanel on Main Page: The adminPanel option has been completely removed. All link management now happens in the dedicated /links page, making the public view cleaner and safer.

🤝 Contributing

Contributions are what make the open-source community amazing! Any contributions you make are greatly appreciated.

How to Contribute:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Guidelines:

Follow clean code principles
Avoid unnecessary dependencies
Performance-first mindset
Write clear commit messages

📜 License

MIT License — Free for personal and commercial use.

See LICENSE for more information.

☕ Support the Project

If you like LinkGrid, consider supporting development:

⭐ Star the repository — it helps others discover LinkGrid!

📬 Contact

VEX – @VEX_SL_ – hamzaowad1713@gmail.com

Project Link: https://github.com/VEX-SL/linkgrid

Made with ❤️ and JavaScript

⭐ Star us on GitHub — it helps!

FilesExpand file tree

README.md

Latest commit

History