# Link shortener

A self-hosted URL shortener for marketing teams, built with Next.js, TypeScript and PostgreSQL. It covers custom slugs on your own domain, QR codes, privacy-friendly click stats by day, referrer and country, expiry, password links, tags and a REST API with personal API keys.

- Framework: Next.js (JavaScript)
- Category: Apps / Newsletters and links
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/apps/marketing/link-shortener-template
- Updated: 2026-11-21

## Features

- Short links on your own domain with a custom slug or a random six-character one that leaves out look-alike characters; slugs are case-insensitive and app paths can't be taken
- Redirects with one query on the unique slug index and a 302, with the click counted after the response has gone
- A QR code for every link, downloadable as SVG for print or a 1024 px PNG
- Clicks by day for 7, 30 or 90 days with the numbers underneath, top referring domains and countries, with no IP address, cookie or user agent stored and link previews and bots not counted
- Link expiry, optional passwords stored as salted scrypt hashes with rate-limited tries, tags, search and a preview page that shows where a link goes
- A REST API to create, list, update and delete links and read their stats, with personal API keys stored only as a hash
- Owner, admin and member roles with invitations by email or link; everyone can delete the links they made, owners and admins any
- A demo Asheville coffee roaster team with 16 links and 90 days of clicks, removed in one click, and WCAG 2.2 AA in light and dark

## What you need

- A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
- To run it locally: Node.js 22.12 or newer, npm, and Docker for a local PostgreSQL
- Recommended: a short domain added as a custom domain with APP_URL set to it, so copied links, QR codes and API answers use it
- Optional: a CDN in front of the app that adds a country header; without one every click counts under Unknown
- Optional: RESEND_API_KEY and EMAIL_FROM to email invitations and password resets, and GitHub or Google keys for team sign-in

## About

The team's name, website and contact email are edited in the app under Settings, Short domain, the time zone for daily click counts with TZ, what counts as a click in src/lib/links/clicks.ts and the reserved slugs in src/lib/links/slugs.ts; the demo Asheville Coffee Roasters team is in src/lib/demo, and its press kit link's password is blueridge. A click only adds one to a daily counter per link, referrer domain and country, while team members' sign-in sessions keep their IP address and browser, as Better Auth does by default. Countries come only from a header a CDN such as Cloudflare adds, and Light Cloud adds none, so every click counts under Unknown unless a CDN sits in front of the app. The API limit of 120 requests a minute per key and the password-attempt limit are kept in memory per instance, so they are looser when several instances run. Light Cloud apps scale to zero, so the first click after a quiet spell waits while the app starts unless you set a minimum of one instance.

## Variables

- `AUTH_SECRET`: generated

## Questions

### Is there a free self-hosted URL shortener with click stats?

Yes. This link shortener is MIT licensed and built with Next.js 16, PostgreSQL, Drizzle ORM and Better Auth. It shows clicks by day, referrer and country, makes QR codes, and runs with no third-party keys.

### Does this link shortener store IP addresses?

Not for clicks. A click only adds one to a daily counter per link, referring domain and country, and no IP address, cookie, user agent or full referrer URL is stored. Team members' sign-in sessions keep their IP address and browser, as Better Auth does by default.

### Can I use my own short domain like go.mycompany.com?

Yes. Point the domain at the app, add it as a custom domain on your host and set APP_URL to it. Copied links, QR codes and API answers then use that domain.

### Why does the shortener redirect with 302 instead of 301?

A 301 is cached by browsers, so later clicks would never reach the app: you couldn't change where a link goes and the clicks wouldn't be counted. A 302 keeps both working.

### Why do my link clicks show the country as Unknown?

The country comes only from a header the proxy or CDN in front of the app adds, such as Cloudflare's cf-ipcountry, and the app never looks up an IP address itself. Light Cloud adds no such header, so put a CDN in front of the app to see countries.
