ngshiheng / atomic-url

A serverless URL shortener built using Cloudflare Worker & KV

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

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

• Table of Contents
• Requirements
• Setup
  • Installation
  • Creating KV
• Optional: CI/CD
• Usage
• Deployment
• Contributing
  • Steps

Requirements

• Get a Cloudflare account
• Install Wrangler CLI for Cloudflare Workers deployment

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

atomic-url's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• chore(deps): update dependency eslint to v9
• fix(deps): update dependency itty-router to v5

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update dependency semantic-release to v23
• fix(deps): update dependency nanoid to v5

Detected dependencies

github-actions

.github/workflows/ci.yml

• actions/checkout v4
• actions/setup-node v4
• cloudflare/wrangler-action v3.4.1
• actions/checkout v4
• grafana/k6-action v0.3.1
• actions/checkout v4
• actions/setup-node v4
• actions/checkout v4
• actions/setup-node v4
• cloudflare/wrangler-action v3.4.1

.github/workflows/lint.yml

• actions/checkout v4
• actions/setup-node v4

npm

package.json

• itty-router 2.6.6
• nanoid 4.0.2
• serverless-cloudflare-workers 1.2.0
• eslint 8.57.0
• prettier 3.2.5
• semantic-release 19.0.5

---

• Check this box to trigger a request for Renovate to run again on this repository

feat: add authentication

feat: allow custom link creation