{"id":17694831,"url":"https://github.com/ngshiheng/atomic-url","last_synced_at":"2025-05-05T21:20:55.013Z","repository":{"id":38211888,"uuid":"441791756","full_name":"ngshiheng/atomic-url","owner":"ngshiheng","description":"A serverless URL shortener built using Cloudflare Worker \u0026 KV","archived":false,"fork":false,"pushed_at":"2025-04-21T17:56:09.000Z","size":620,"stargazers_count":46,"open_issues_count":6,"forks_count":8,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-01T03:48:20.104Z","etag":null,"topics":["bitly","cloudflare-workers","javsascript","serverless","tinyurl","urlshortener"],"latest_commit_sha":null,"homepage":"https://s.jerrynsh.com","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ngshiheng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ngshiheng"]}},"created_at":"2021-12-26T02:03:47.000Z","updated_at":"2025-04-01T01:55:53.000Z","dependencies_parsed_at":"2023-01-31T19:46:19.846Z","dependency_job_id":"14a09d81-323e-47c7-8381-dc2e079780d0","html_url":"https://github.com/ngshiheng/atomic-url","commit_stats":{"total_commits":135,"total_committers":3,"mean_commits":45.0,"dds":"0.37777777777777777","last_synced_commit":"c7eb4d28347fd69b4078f37efaf2a3b2f81e2151"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngshiheng%2Fatomic-url","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngshiheng%2Fatomic-url/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngshiheng%2Fatomic-url/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngshiheng%2Fatomic-url/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngshiheng","download_url":"https://codeload.github.com/ngshiheng/atomic-url/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252577108,"owners_count":21770733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitly","cloudflare-workers","javsascript","serverless","tinyurl","urlshortener"],"created_at":"2024-10-24T13:49:52.243Z","updated_at":"2025-05-05T21:20:54.998Z","avatar_url":"https://github.com/ngshiheng.png","language":"HTML","funding_links":["https://github.com/sponsors/ngshiheng"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003cstrong\u003eAtomic URL\u003c/strong\u003e\u003c/h1\u003e\n\n```mermaid\nflowchart TD\n  api([API Clients])\n  browser([Browser])\n  worker(\u003ca href='https://developers.cloudflare.com/workers/'\u003eWorker\u003c/a\u003e):::cf\n  kv[(\u003ca href='https://developers.cloudflare.com/workers/runtime-apis/kv/'\u003eKV\u003c/a\u003e)]:::cf\n  cache[(\u003ca href='https://developers.cloudflare.com/workers/runtime-apis/cache/'\u003eCache\u003c/a\u003e)]:::cf\n\n  classDef cf stroke:#FFC500,stroke-width:2px\n\n  subgraph Cloudflare\n    worker\n    kv\n    cache\n  end\n\n  kv \u003c--\u003e worker\n  cache \u003c--\u003e worker\n  worker \u003c--\u003e api\n  worker \u003c--\u003e browser\n```\n\nDesigning a URL shortener such as [TinyURL](https://tinyurl.com/) and [Bitly](https://bitly.com/) is one of the most common System Design interview questions in software engineering.\n\nWhile meddling around with Cloudflare Worker, it gave me an idea to build an actual URL shortener that can be used by anyone.\n\nThis is a proof of concept (POC) of how one builds an actual URL shortener service using serverless computing.\n\n[Read more...](https://jerrynsh.com/i-built-my-own-tiny-url/)\n\n## Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [Requirements](#requirements)\n- [Setup](#setup)\n  - [Installation](#installation)\n  - [Creating KV](#creating-kv)\n- [Optional: CI/CD](#optional-cicd)\n- [Usage](#usage)\n- [Deployment](#deployment)\n- [Contributing](#contributing)\n  - [Steps](#steps)\n\n## Requirements\n\n-   Get a [Cloudflare](https://www.cloudflare.com/) account\n-   Install [Wrangler](https://developers.cloudflare.com/workers/wrangler/cli-wrangler/) CLI for Cloudflare Workers deployment\n\n## Setup\n\nCheck out Steps 1 to 3 of this [Get Started Guide](https://developers.cloudflare.com/workers/get-started/guide/) to setup a Cloudflare account.\n\n[Read more](https://developers.cloudflare.com/workers/wrangler/configuration/#configure-wranglertoml) about configuring `wrangler.toml`.\n\n### Installation\n\nThis project is initialized using the [`itty-router`](https://github.com/kwhitley/itty-router) [worker template](https://github.com/cloudflare/worker-template-router).\n\n```sh\nnpm ci\n```\n\n### Creating KV\n\nSince we're using KV as our storage, we need to first create it.\n\n```sh\nwrangler kv:namespace create \"URL_DB\"\nwrangler kv:namespace create \"URL_DB\" --preview\n```\n\nFor creating these KV namespaces, remember to update your [`wrangler.toml`](./wrangler.toml) file to include the namespace bindings accordingly.\n\n## Optional: CI/CD\n\n1. This project uses [Wrangler actions](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler) to automatically publish worker. To do so, add `CF_API_TOKEN` into your GitHub repository secrets. You can [create your API token](https://dash.cloudflare.com/profile/api-tokens) using the `Edit Cloudflare Workers` template.\n\n2. This project also uses [semantic-release](https://github.com/semantic-release/npm) to automatically publish to NPM. To enable this, you will need to create a `NPM_TOKEN` via [npm create token](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens) and add it to your GitHub repository secrets.\n\n## Usage\n\nTo try out the project locally, simply run `wrangler dev`.\n\n## Deployment\n\n\u003e **NOTE**\n\u003e The deployment of this project is done using GitHub Actions CI/CD. For more details, check out [ci.yml](./.github/workflows/ci.yml) and [this article](https://jerrynsh.com/how-i-setup-ci-cd-pipeline-for-cloudflare-worker/).\n\n1. Before publishing your code you need to edit [`wrangler.toml`](./wrangler.toml) file and add your Cloudflare `account_id` - more information about configuring and publishing your code can be found [in the documentation](https://developers.cloudflare.com/workers/learning/getting-started#7-configure-your-project-for-deployment).\n\n2. [Create 2 KV](#creating-kv) and update your `wrangler.toml` file to include the namespace bindings accordingly.\n\n3. To publish any new changes to your Cloudflare Worker, run `wrangler publish -e \u003cenv\u003e` where `\u003cenv\u003e` could `staging` or `production`.\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n### Steps\n\n1. Fork this\n2. Create your feature branch (`git checkout -b jimmy/fooBar`)\n3. Code\n4. Commit your changes (`git commit -am 'feat: add some fooBar'`, make sure that your commits are [semantic](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716))\n5. Push to the branch (`git push origin jimmy/fooBar`)\n6. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngshiheng%2Fatomic-url","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngshiheng%2Fatomic-url","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngshiheng%2Fatomic-url/lists"}