URL Shortener

URL shortener using Cloudflare Workers & Workers KV

⚡ Reference

Assuming your instance is deployed to go.example.com

• go.example.com/admin is the admin portal. Add & remove redirects (shortened URLs) here
• go.example.com/api is the primary API endpoint (but you shouldn't need to touch this!)

🔋 Getting Started

Requirements

1. NodeJS and npm
2. git

Create Google Sign-In authorization credentials

1. Go to the Credentials page
2. Click Create credentials > OAuth client ID
3. Select the Web application application type
4. Name your OAuth 2.0 client and click Create
5. Take note of the client ID - you will need it in future steps

Log in to Cloudflare Wrangler

1. If you haven't already, you will need to log in to Cloudflare Wrangler
   wrangler login

Create the Cloudflare DNS records & Workers

1. Go to your Cloudflare dashboard
2. Select the domain which this redirection service will be running from. We'll use example.com in this README
3. Take note of the zone ID and account ID - you will need it in future steps (use CTRL+F or ⌘+F to find it on the page)
4. Select the DNS tab. The URL will look something like dash.cloudflare.com/0123456789abcdef0123456789abcdef/example.com/dns
5. Add a new record of the AAAA type, with the name as go and the content as 100::. This will allow us to host our URL shortener at go.example.com
6. Add a new record of the AAAA type, with the name as go-dev and the content as 100::. This is what we'll use as our testing environment
7. Select the Workers tab. If this is your first time using Workers, you'll need to pick a name and select the free plan
8. Click Manage KV namespaces. The URL will look something like dash.cloudflare.com/0123456789abcdef0123456789abcdef/workers/kv/namespaces
9. Add two namespaces, we'll call them URL_SHORTENER and URL_SHORTENER_DEV, but the names really don't matter.
10. Take note of the ID of each of the namespaces

Local Setup

From the command line

1. Clone this project
   git clone https://github.com/DarkMatterMatt/cf-url-shortener
2. Navigate to the newly created directory
   cd cf-url-shortener
3. Install dependencies
   npm install
4. Copy the example Wrangler configuration file so you can add your own details
   cp wrangler.example.toml wrangler.toml
5. Change the account_id and zone_id to the one you copied earlier
6. Change the example.com routes to match your domain (if you were using example.com you wouldn't have to make any changes)
7. In the first kv_namespaces, change both id and preview_id to the URL_SHORTENER_DEV ID that you copied earlier. This will be the KV store for your development environment
8. In the second kv_namespaces, change the id to the URL_SHORTENER ID that you copied earlier. This will be the KV store for your production environment
9. Change the GOOGLE_CLIENT_ID to the one you copied earlier
10. Change the AUTHORIZED_EMAIL_REGEX variables to choose who can modify your redirects. This is the only security for your application and by default anyone can modify your redirects in the development environment. This variable is a regular expression, and you will need to double escape any backslashes (i.e. replace every \ with \\). To only allow one email to modify your redirects, set it to ^matt@example\\.com$

First Deployment

1. Deploy to the development environment
   npm run send
2. Check that it all works as expected - go to https://go-dev.example.com/admin and create a redirect, then test that https://go-dev.example.com/myNewRedirect correctly forwards you to where you want to go
3. Deploy to production! (Don't forget that you'll need to set up your redirects again in the production environment, https://go.example.com/admin)
   npm run send:prod

💜 Contributing

Pull requests for features, bug fixes & unit tests are always welcome! If you find a bug or typo please open an issue.