{"id":15723316,"url":"https://github.com/erisa/worker-links","last_synced_at":"2025-10-19T13:32:31.816Z","repository":{"id":43874994,"uuid":"349199855","full_name":"Erisa/worker-links","owner":"Erisa","description":"A simple URL Shortener for Cloudflare Workers!","archived":false,"fork":false,"pushed_at":"2025-02-15T03:49:58.000Z","size":251,"stargazers_count":78,"open_issues_count":1,"forks_count":15,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T12:08:43.160Z","etag":null,"topics":["cloudflare","cloudflare-workers","hono","honojs","link-shortener"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/Erisa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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":"Erisa"}},"created_at":"2021-03-18T19:51:21.000Z","updated_at":"2025-04-06T13:08:28.000Z","dependencies_parsed_at":"2023-11-27T03:40:04.206Z","dependency_job_id":"af181cfb-d6c6-41c8-bd65-bf61b2bb6372","html_url":"https://github.com/Erisa/worker-links","commit_stats":{"total_commits":89,"total_committers":10,"mean_commits":8.9,"dds":0.4269662921348315,"last_synced_commit":"6305a297ec68f3bda461a29323e9b13b93d606ac"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erisa%2Fworker-links","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erisa%2Fworker-links/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erisa%2Fworker-links/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erisa%2Fworker-links/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Erisa","download_url":"https://codeload.github.com/Erisa/worker-links/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248036067,"owners_count":21037092,"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":["cloudflare","cloudflare-workers","hono","honojs","link-shortener"],"created_at":"2024-10-03T22:11:09.341Z","updated_at":"2025-10-19T13:32:26.784Z","avatar_url":"https://github.com/Erisa.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Erisa"],"categories":[],"sub_categories":[],"readme":"# Worker Links (URL Shortener)\n\nA simple URL Shortener for Cloudflare Workers, using Workers KV. Redirect short URLs at the edge of the Cloudflare network to keep latency down and access fast!\n\nI run this code in production on [erisa.link](https://erisa.link/example), though the root name redirects and without the secret it doesn't make a very good demo.\n\nIt was made for my personal use but is available publicly in the hopes that it may be useful to someone somewhere.\n\n## Deploy (simple)\n\nWrangler 2 is required now, but should be handled automatically for `npm run` commands.  \nTo run manual wrangler commands, try `npx wrangler`.\n\nSimple steps:\n\n- `npm install`\n- `npm run addsecret`\n- `npm run createkv` (follow `wrangler.toml` instructions)\n- `npm run deploy`\n\n## Deploy (More involved)\n\nTo deploy to your Cloudflare Workers account, edit the relevant entries in `wrangler.toml`, add a secret with `wrangler secret put WORKERLINKS_SECRET` and use `wrangler publish`.\n\n## Debugging\n\nFor debuggging, you can use `npm run dev` (Which runs `wrangler dev --local`). To change the secret used in this mode, edit the `.dev.vars` file.\n\nYou can also debug on the edge with `wrangler dev`, though you will need to first configure a prepview namespace in `wrangler.toml` and add the `WORKERLINKS_SECRET` secret to the Worker.\n\n## (Optional) User Interface\n\nIf `ENABLE_INDEX_FORM` is enabled in `wrangler.toml`, an optional UI form is available when visiting the Worker in a browser, allowing easy creation of links:\n\n![](https://up.erisa.uk/firefox_GPuOu50qKC.png)\n\n## Usage\n\nOnce deployed, interacting with the API should be rather simple. It's based on headers, specifically with the `Authorization` and `URL` headers.\n\nTo create a short URL with a random URL, send a `POST` to `/` with `Authorization` and `URL` headers:\n\n```json\nerisa@Tuturu:~$ curl -X POST -H \"Authorization: mysecret\" -H \"URL: https://erisa.uk\" https://erisa.link/\n{\n  \"message\": \"URL created succesfully.\",\n  \"key\": \"q2w083eq\",\n  \"shorturl\": \"https://erisa.link/q2w083eq\",\n  \"longurl\": \"https://erisa.uk\"\n}\n```\n\nAnd you can test it worked if you wish:\n\n```http\nerisa@Tuturu:~$ curl https://erisa.link/q2w083eq -D-\nHTTP/2 302\ndate: Fri, 11 Sep 2020 12:43:04 GMT\ncontent-length: 0\nlocation: https://erisa.uk\nserver: cloudflare\n..other ephemeral headers..\n```\n\nTo create or update a custom short URL, send a `PUT` to the intended target URL:\n\n```json\nerisa@Tuturu:~$ curl -X PUT -H \"Authorization: mysecret\" -H \"URL: https://erisa.uk\" https://erisa.link/mywebsite\n{\n  \"message\": \"URL created succesfully.\",\n  \"key\": \"mywebsite\",\n  \"shorturl\": \"https://erisa.link/mywebsite\",\n  \"longurl\": \"https://erisa.uk\"\n}\n```\n\nAnd to delete an existing shortlink, send a `DELETE` to it with only the `Authorization` header:\n\n```json\nerisa@Tuturu:~$ curl -X DELETE -H \"Authorization: mysecret\" https://erisa.link/keytodelete\n{\n  \"message\": \"Short URL deleted succesfully.\",\n  \"key\": \"keytodelete\",\n  \"shorturl\": \"https://erisa.link/keytodelete\",\n  \"longurl\": \"https://erisa.uk\"\n}\n```\n\nYou can also bulk create multiple shortlinks at once by sending a `POST` to `/` with no `URL` header and with a JSON body instead:\n\n```json\nerisa@Tuturu:~$ curl -X POST -H \"Authorization: mysecret\" https://erisa.link/ \\\n    -H 'Content-Type: application/json' \\\n    -d '{ \"/short1\": \"https://example.com\", \"/mywebsite\": \"https://erisa.uk\" }'\n{\n  \"message\": \"URLs created successfully\",\n  \"entries\": [\n    {\n      \"key\": \"short1\",\n      \"shorturl\": \"https://erisa.link/short1\",\n      \"longurl\": \"https://example.com\"\n    },\n    {\n      \"key\": \"mywebsite\",\n      \"shorturl\": \"http://erisa.link/mywebsite\",\n      \"longurl\": \"https://erisa.uk\"\n    }\n  ]\n}\n```\n\nYou can list all URLs by sending a `GET` to `/` (with the `Authorization` header set to your secret, of course).\n\n```json\nkot@Starry:~$ curl -H \"Authorization: mysecret\" \"https://erisa.link/?prefix=%2F\u0026limit=1\"\n{\n    \"list_complete\": false,\n    \"cursor\": \"AAAAAJhOXekucRAqut7Xs7Q2f09GCZyStWBfONvq6u5JP05Bg-z5FM5gf7krRaDrsvyxqfDuvFWUHIZp2n9OZ7Au92h-x68xwg8-bwerIoPd7fesG5w-ZB6f6oXopZHNXDCscmVUQ0OIaDEOx_6pruyEcCKfD3WpOstj6lO_sYJG_zQKdBgmYvLoMFQpK-cK7t8mCLWQA2t351xc9sJ08SM0JniY73t7bOdSxF3ADVTV6ihMSti0Z6svhpknfCn9VHjT\",\n    \"links\": [\n        {\n            \"key\": \"/0031qr7q7\"\n        },\n        {\n            \"key\": \"/00ybqita\"\n        },\n        {\n            \"key\": \"/02ji9wlg\"\n        }\n    ]\n}\n```\n\nThe endpoint is paginated by default (1000/page). Just send `cursor` in the query string to access the next page.\n\nYou can set `limit` in the query string to `0` to retrieve all URLs.\n\nYou can also view URLs from your Cloudflare Dashboard:\n`Cloudflare Dashboard -\u003e Workers -\u003e KV -\u003e View` on the namespace.\n\n## ShareX\n\nTo use worker-links as a URL Shortener in ShareX, create a file with a `.sxcu` extension (ex. `worker-links.sxcu`) and copy-paste the following:\n\n```json\n{\n  \"Version\": \"15.0.0\",\n  \"Name\": \"worker-links\",\n  \"DestinationType\": \"URLShortener\",\n  \"RequestMethod\": \"POST\",\n  \"RequestURL\": \"https://erisa.link\",\n  \"Headers\": {\n    \"Authorization\": \"mysecret\",\n    \"URL\": \"{input}\"\n  },\n  \"Body\": \"JSON\",\n  \"URL\": \"{json:shorturl}\"\n}\n```\n\nReplace `RequestURL` with the URL of your choice and `Authorization` with your worker link's secret.\n\nNow open the `.sxcu` file. It should make worker-links as your active custom URL Shortener.  \nIf not, click on **Destinations** -\u003e **URL Shortener** and choose **Custom URL Shortener**.\n\n## Plausible Analytics\n\nTo get statistics for your short URLs with Plausible Analytics, define a `PLAUSIBLE_HOST` secret set to the URL of your Plausible instance. For example, `https://plausible.io/`.\n\n## Security\n\nThis code is relatively simple but still, if you find any security issues that can be exploited publicly, please reach out to me via email: `erisa (at) erisa.uk` with any relevant details.\n\nIf you don't have access to Workers KV you're welcome to test these issues on my live `erisa.link`, provided you don't send excessive (constant) requests or delete/modify any keys except ones created by you or the `/sample` key.\n\nIf I don't respond to your email for whatever reason please feel free to publicly open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferisa%2Fworker-links","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferisa%2Fworker-links","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferisa%2Fworker-links/lists"}