{"id":15723465,"url":"https://github.com/civfso/junction","last_synced_at":"2025-04-20T23:30:40.876Z","repository":{"id":90701691,"uuid":"607412254","full_name":"civfso/junction","owner":"civfso","description":"Short-URL service built for Cloudflare Workers, Pages, and KV.","archived":true,"fork":false,"pushed_at":"2024-01-11T17:09:25.000Z","size":510,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T06:08:49.772Z","etag":null,"topics":["cloudflare","cloudflare-workers","hono","serverless","shortlink"],"latest_commit_sha":null,"homepage":"https://tycrek.link","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/civfso.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}},"created_at":"2023-02-27T23:19:34.000Z","updated_at":"2025-03-03T06:15:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"0a488434-809c-472c-a7bc-21e1cefc2c8f","html_url":"https://github.com/civfso/junction","commit_stats":null,"previous_names":["civfso/junction"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civfso%2Fjunction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civfso%2Fjunction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civfso%2Fjunction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/civfso%2Fjunction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/civfso","download_url":"https://codeload.github.com/civfso/junction/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249977341,"owners_count":21354855,"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","serverless","shortlink"],"created_at":"2024-10-03T22:11:49.511Z","updated_at":"2025-04-20T23:30:40.382Z","avatar_url":"https://github.com/civfso.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n🔗 junction\n===\n\n*Short-URL service built for Cloudflare Workers, Pages, and KV.*\n\n\u003c/div\u003e\n\n## Getting Started\n\nAs of right now, junction is best used with ShareX. There is a basic user panel that can be used to shorten URL's as well. I've also successfully made an [iOS Siri Shortcut](https://github.com/tycrek/junction/raw/master/Shorten%20URL.shortcut) that uses junction to shorten links.\n\n```bash\ngit clone https://github.com/tycrek/junction.git \u0026\u0026 cd junction\nnpm i\n```\n\n### Bindings\n\nFirst, create a KV namespace and bind it to the worker. You can do this in the [Workers dashboard](https://dash.cloudflare.com/?to=/:account/workers/kv/namespaces).\n\njunction expects the namespace to be called `junction`. For publishing, ensure your project is also called `junction`.\n\n### Environment Variables\n\nFor local dev, put these variables in a file called `.dev.vars` (formatted the same as a typical `.env`).\n\nFor production, set these values on the dashboard.\n\n- **`TOKEN`** is used for requests to junction's KV API. Set to a random string.\n\n## Usage\n\nTo run **locally**, run `npm run dev`. This will launch the Wrangler dev server (press `B` to open the browser).\n\nTo **publish**, run `npm run publish`. This will build the project and publish it to Cloudflare Workers, under the project name `junction`.\n\n## API\n\n### `GET /api/shorten/:url`\n\nRequires a `Authorization` header with a `Bearer` token. This token must match the `TOKEN` environment variable.\n\n### `GET /:key`\n\nRedirects to the URL associated with the key, if it exists.\n\n## Adjusting the response type\n\nBy default, the API returns a JSON response with the following format:\n\n```json\n{\n  \"key\": \"abc123\",\n  \"url\": \"https://example.com/abc123\"\n}\n```\n\nYou may request alternate response types by adding an `Accept` header to your request. The **Response** will match the format of the `Accept` type.\n\nAt this time, junction supports the following response types:\n\n### Supported response types\n\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003ccode\u003eAccept\u003c/code\u003e type\u003c/th\u003e\n\u003cth\u003e\nResponse format\n\u003c/th\u003e\n\u003c/tr\u003e\n\n\u003c!-- application/json --\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003eapplication/json\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\n```json\n{\n  \"key\": \"12ab0\",\n  \"url\": \"https://example.com/12ab0\"\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c!-- text/plain --\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003etext/plain\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\n```\nhttps://example.com/12ab0\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c!-- text/html --\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003etext/html\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\n```html\n\u003ca href=\"https://example.com/12ab0\"\u003ehttps://example.com/12ab0\u003c/a\u003e\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c!-- application/x-www-form-urlencoded --\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003eapplication/x-www-form-urlencoded\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\n```\nurl=https%3A%2F%2Fexample.com%2F12ab0\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c!-- application/xml --\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003eapplication/xml\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e\n\n```xml\n\u003cshort\u003e\n  \u003ckey\u003e12ab0\u003c/key\u003e\n  \u003curl\u003ehttps://example.com/12ab0\u003c/url\u003e\n\u003c/short\u003e\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c/table\u003e\n\njunction does **not** support multiple `Accept` types. If you request multiple types, it may not behave as expected. I'll fix this in the future.\n\n## ShareX setup\n\n1. Download and install [ShareX](https://tycrek.link/b4d55).\n2. Open ShareX and click `Destinations` in the left sidebar, then click `URL Shortener`, then select **`Custom URL shortener`**.\n3. Click `Destinations` again, then click `Custom uploader settings...`.\n4. Create a new uploader with the following settings:\n\n   | Setting | Value |\n   | ------- | ----- |\n   | Name | `junction` |\n   | Destination type | `URL shortener` |\n   | Method | `GET` |\n   | Request URL | `https://YOUR.DOMAIN.HERE/api/shorten/{input}` |\n   | Body | `No body` |\n   | URL | `https://YOUR.DOMAIN.HERE/{json:key}` |   \n\n   Add an `Authorization` header with the value `Bearer YOUR-TOKEN-FROM-ABOVE`.\n\n5. In the bottom left of the **Custom uploader settings** window, choose **`junction`** as your URL shortener.\n\nTo shorten links with ShareX, either set a keybind or right-click the tray icon and select `Upload` \u003e `Shorten URL...`. The link will be copied to your clipboard automatically.\n\n## Stack\n\n- [Cloudflare Workers](https://developers.cloudflare.com/workers/) - serverless hosting (technically [Cloudflare Pages](https://pages.cloudflare.com/), because I prefer using the JAMstack frontend method)\n- [Hono.js](https://hono.dev/) - backend\n- [Pagery](https://github.com/tycrek/pagery) - frontend (landing page)\n\n#### Why Pages, not Workers? There's only one file!\n\nI chose Pages because I preferred Pages [Advanced Mode](https://developers.cloudflare.com/pages/platform/functions/advanced-mode/) + asset upload over Workers storing HTML contents in KV. [Cloudflare themselves recommends this](https://developers.cloudflare.com/workers/platform/sites):\n\n\u003e Consider using Cloudflare Pages for hosting static applications instead of Workers Sites.\n\nI also found this way easier to incorporate my custom JAMstack framework, [Pagery](https://github.com/tycrek/pagery). So does a service like this require a Pages site? Not really. But I plan to add a user panel in the future, and Pages is a much better fit for that.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcivfso%2Fjunction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcivfso%2Fjunction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcivfso%2Fjunction/lists"}