Skip to content

A serverless URL shortener built using Cloudflare Worker & KV

License

Notifications You must be signed in to change notification settings

ngshiheng/atomic-url

Repository files navigation

Atomic URL

flowchart TD
  api([API Clients])
  browser([Browser])
  worker(<a href='https://developers.cloudflare.com/workers/'>Worker</a>):::cf
  kv[(<a href='https://developers.cloudflare.com/workers/runtime-apis/kv/'>KV</a>)]:::cf
  cache[(<a href='https://developers.cloudflare.com/workers/runtime-apis/cache/'>Cache</a>)]:::cf

  classDef cf stroke:#FFC500,stroke-width:2px

  subgraph Cloudflare
    worker
    kv
    cache
  end

  kv <--> worker
  cache <--> worker
  worker <--> api
  worker <--> browser
Loading

Designing a URL shortener such as TinyURL and Bitly is one of the most common System Design interview questions in software engineering.

While meddling around with Cloudflare Worker, it gave me an idea to build an actual URL shortener that can be used by anyone.

This is a proof of concept (POC) of how one builds an actual URL shortener service using serverless computing.

Read more...

Table of Contents

Requirements

Setup

Check out Steps 1 to 3 of this Get Started Guide to setup a Cloudflare account.

Read more about configuring wrangler.toml.

Installation

This project is initialized using the itty-router worker template.

npm ci

Creating KV

Since we're using KV as our storage, we need to first create it.

wrangler kv:namespace create "URL_DB"
wrangler kv:namespace create "URL_DB" --preview

For creating these KV namespaces, remember to update your wrangler.toml file to include the namespace bindings accordingly.

Optional: CI/CD

  1. This project uses Wrangler actions to automatically publish worker. To do so, add CF_API_TOKEN into your GitHub repository secrets. You can create your API token using the Edit Cloudflare Workers template.

  2. This project also uses semantic-release to automatically publish to NPM. To enable this, you will need to create a NPM_TOKEN via npm create token and add it to your GitHub repository secrets.

Usage

To try out the project locally, simply run wrangler dev.

Deployment

NOTE The deployment of this project is done using GitHub Actions CI/CD. For more details, check out ci.yml and this article.

  1. Before publishing your code you need to edit wrangler.toml file and add your Cloudflare account_id - more information about configuring and publishing your code can be found in the documentation.

  2. Create 2 KV and update your wrangler.toml file to include the namespace bindings accordingly.

  3. To publish any new changes to your Cloudflare Worker, run wrangler publish -e <env> where <env> could staging or production.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Steps

  1. Fork this
  2. Create your feature branch (git checkout -b jimmy/fooBar)
  3. Code
  4. Commit your changes (git commit -am 'feat: add some fooBar', make sure that your commits are semantic)
  5. Push to the branch (git push origin jimmy/fooBar)
  6. Create a new Pull Request