- TypeScript 38%
- CSS 21.6%
- JavaScript 13.3%
- PowerShell 12.2%
- Python 11%
- Other 3.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .forgejo/workflows | ||
| brand | ||
| extension | ||
| images | ||
| pterodactyl | ||
| scripts | ||
| web | ||
| .gitignore | ||
| gen-icons.ps1 | ||
| README.md | ||
ShortLink
Self-hosted URL shortener: Next.js web app, Postgres storage, Firefox extension, and a Pterodactyl egg for deploy.
Live instance pattern: shorten links at your BASE_URL, manage them at /admin, install the extension from Forgejo releases.
Screenshots
URL bar page action:
Extension popup:
Custom code (hover the hint under the button):
Settings:
Features
- Shorten any URL from the homepage (optional custom code)
GET /:coderedirects and tracks clicks- Password-protected
/admindashboard (list + delete links) - Firefox MV3 extension — toolbar popup, URL-bar page action, context menus
- Auto-built
.xpireleases on Forgejo (optional AMO signing) - Pterodactyl egg: git pull → build → start on each boot
Project layout
web/ Next.js 15 app (UI, API, admin, Postgres store)
extension/ Firefox Manifest V3 add-on
images/ README screenshots
brand/ Source SVG icons (site + extension)
pterodactyl/ Egg + entrypoint for panel hosting
scripts/ XPI packaging + AMO signing helpers
.forgejo/ Release workflow
Web app
Requirements
- Node.js 22+
- Postgres
Setup
cd web
npm install
cp .env.example .env.local
Edit .env.local:
| Variable | Purpose |
|---|---|
BASE_URL |
Public origin used in generated short URLs (e.g. https://short.example.com) |
PORT |
Listen port (default 3000) |
DATABASE_URL |
Postgres connection string |
ADMIN_PASSWORD |
Password for /admin (leave empty to disable login) |
FORGEJO_API_URL |
Optional — latest-release download on the homepage |
FORGEJO_REPO |
Optional — owner/repo for that release lookup |
Create the database (example):
sudo -u postgres createuser shortlink
sudo -u postgres createdb -O shortlink shortlink
sudo -u postgres psql -c "ALTER USER shortlink PASSWORD 'shortlink';"
Run
npm run dev # http://localhost:3000
Production:
npm run build && npm start
Tables are created automatically on first use.
API
POST /api/shorten
{ "url": "https://example.com/long", "customCode": "optional" }
Response:
{ "code": "Ab12Cd", "shortUrl": "https://your.host/Ab12Cd" }
GET /:code — 302 to the stored URL (increments clicks).
Firefox extension
Points at your ShortLink instance (default host permission: https://short.hexium.cc/*).
Temporary install (dev)
- Run the web app.
- Firefox →
about:debugging→ This Firefox → Load Temporary Add-on… - Pick
extension/manifest.json.
Release install
Download the signed .xpi from the repo’s Forgejo releases and open it in Firefox.
Unsigned builds: load via about:debugging, or use Firefox Developer Edition / Nightly.
What it does
- Popup to shorten the current tab (or a pasted URL)
- Optional custom code + dark mode in settings
- Context menu on links / page
- Page action in the URL bar on
http(s)pages
Releases (Forgejo Actions)
Workflow: .forgejo/workflows/release-extension.yml
- Push to
main(extension/scripts changes) → auto-bumps patch version, builds.xpi, publishes a release - Tag
vX.Y.Z→ release for that version - Manual run → enter a version; creates
v<version>+ release
Optional AMO signing: set repository secrets AMO_JWT_ISSUER and AMO_JWT_SECRET from AMO API keys.
Artifacts look like shortlink-extension-vX.Y.Z-signed.xpi (or unsigned if signing is skipped).
Icons
# from repo root (needs web/ node_modules for @resvg/resvg-js)
powershell -ExecutionPolicy Bypass -File .\gen-icons.ps1
Renders brand/shortlink-icon.svg → web favicons, and brand/shortlink-icon-extension.svg → extension PNGs.
Pterodactyl
Import pterodactyl/egg.json. On each start the entrypoint pulls the configured Forgejo branch, installs, builds, and runs the app.
Set at least:
GIT_ADDRESS/GIT_BRANCH/ optionalGIT_TOKENDATABASE_URLBASE_URLADMIN_PASSWORD



