URL Shortener (Powering XNa.me)

A simple URL shortener built with Cloudflare Workers and KV Storage. This is source code that Powering XNa.me (a.k.a xName)

Features

• ✅ Shorten long URLs with custom or random slugs
• ✅ Password protection for sensitive links
• ✅ Clean, responsive web interface
• ✅ REST API for CLI/terminal access
• ✅ Automatic redirect handling
• ✅ Fallback to main page for invalid slugs
• ✅ Serverless setup using Cloudflare Workers and KV Storage

Setup

1. Install dependencies:

npm install

2. Set up Wrangler configuration:

# Copy the example configuration
cp wrangler.toml wrangler.production.toml

# Edit wrangler.production.toml with your actual values:
# - Replace "placeholder-kv-namespace-id" with your KV namespace ID
# - Replace "placeholder-domain.com" with your custom domain

3. Set up Cloudflare resources:

   • Create a KV namespace: wrangler kv:namespace create "URLS"
   • Note the KV namespace ID from the output
   • Add your custom domain to Cloudflare (optional)

4. Set Cloudflare API token as a Wrangler secret:

wrangler secret put CLOUDFLARE_API_TOKEN

5. Deploy to Cloudflare Workers:

wrangler deploy

Development

npm run dev

Usage

Web Interface

1. Create Short URL: Visit the main page and enter your long URL
2. Custom Slug: Optionally specify a custom slug, or leave empty for random
3. Password Protection: Optionally set a password to protect the link
4. Access: Visit domain.com/slug to redirect to the original URL

API/CLI Usage

Create shortened URLs from terminal using curl:

Basic URL shortening:

curl -X POST https://your-worker.workers.dev/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very-long-url"}'

With custom slug:

curl -X POST https://your-worker.workers.dev/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/long-url", "slug": "my-custom-slug"}'

With password protection:

curl -X POST https://your-worker.workers.dev/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/secret-url", "password": "mypassword"}'

Complete example with all options:

curl -X POST https://your-worker.workers.dev/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very-long-secret-url",
    "slug": "secret-link",
    "password": "mypassword123"
  }'

API Response:

{
  "shortUrl": "https://your-worker.workers.dev/abc123",
  "originalUrl": "https://example.com/very-long-url",
  "slug": "abc123",
  "createdAt": "2024-01-01T12:00:00.000Z",
  "passwordProtected": false
}

Error Responses:

• 400: Missing URL or invalid request
• 409: Slug already exists

Shell Function (Optional)

Add this to your .bashrc or .zshrc for easy CLI usage:

shorten() {
  local url="$1"
  local slug="$2"
  local password="$3"
  local data="{\"url\":\"$url\""
  
  if [ -n "$slug" ]; then
    data="$data,\"slug\":\"$slug\""
  fi
  
  if [ -n "$password" ]; then
    data="$data,\"password\":\"$password\""
  fi
  
  data="$data}"
  
  curl -X POST https://your-worker.workers.dev/shorten \
    -H "Content-Type: application/json" \
    -d "$data" | jq -r '.shortUrl'
}

Usage: shorten "https://long-url.com" "custom-slug" "optional-password"

Configuration

Wrangler Configuration

The project uses wrangler.toml as an example template. For deployment, you need to:

1. Copy wrangler.toml to wrangler.production.toml
2. Edit wrangler.production.toml with your actual values:
   • id: Replace "placeholder-kv-namespace-id" with your KV namespace ID
   • pattern: Replace "placeholder-domain.com" with your custom domain

Note: wrangler.production.toml is gitignored to keep your secrets safe.

Secrets

The following secret needs to be set via Wrangler:

• CLOUDFLARE_API_TOKEN: Your Cloudflare API token (set via wrangler secret put CLOUDFLARE_API_TOKEN)

Custom Domain Setup

1. Add your domain to Cloudflare
2. Set up DNS records as required
3. Add the domain to your wrangler.production.toml file
4. Deploy with wrangler deploy --config wrangler.production.toml

The worker will automatically route traffic from your custom domain.