short.

Short is a lightweight and simple link shortener working on Cloudflare Workers®.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments
9. Legal

About The Project

The goal of this project is to create a lightweight and simple url shortener that simply runs on Cloudflare Workers® and is deployed by GitHub Actions. It uses the native Cloudflare Workers® SDK without any additional packreges to be as minimal and cheap as possible. Short provides a simple API to create and manage new links.

(back to top)

Built With

(back to top)

Getting Started

This is an explanation of how you can get your own instance of short up and running.

Prerequisites

Before you get started, you need to have a few things ready:

Caution

When you fork the repository unselect "Copy the main branch only" else you will only be able to use the development version.

• Fork the repository to your own account with all branches.
• A Cloudflare® API Key with the necessary permissions to create and manage workers.
  • Follow the instructions here to get your API Key.
• A Cloudflare® KV Namespace to store the links.
  • Follow the instructions here to create a new KV Namespace. (Recommended: Select Dashboard in the documentation)

Deployment

Important

It is mandatory to follow the following steps to ensure that a stable version is deployed. If you want to deploy the development version, you can do so by selecting the main branch in the workflow.

1. Create following secrets in your forked repository: (Settings > Secrets and variables > New Repository Secret)

   • CF_API_TOKEN - Your Cloudflare® API Token
   • CF_KV_ID - Your Cloudflare KV Namespace ID
     • To get your KV Namespace ID, go to your Cloudflare® Dashboard, select your KV Namespace and copy the which is next to the name in the top left.
   • SHORT_API_KEY - Recommended: A random string if you want to secure your API.

2. Activate GitHub Actions in your repository.

   1. Go to the Actions tab in your repository.
   2. Click on the green button I understand my workflows, go ahead and enable them to enable GitHub Actions.

3. Run the workflow 🚀 Deploy.

   1. On your repository page, click on the Actions tab.
   2. Click on the 🚀 Deploy workflow on the left side.
   3. Click on the Run workflow button on the right side.
      1. Click on the Branch: main dropdown.
      2. Select the branch production.
   4. Run the workflow by clicking the green Run workflow button.

4. (Recommended) Install the pull app to the repository. It will automatically update the production branch. Just install it and you are done, everything is preconfigured and will be updated automatically.

🚀 All done! How simple huh? Now you can see your worker active here in your Cloudflare dashboard.

(back to top)

Usage

Short provides a simple API to create and manage new links. The API is secured by an API key which you can set in the secrets of your repository.

For detailed documentation, please refer to the API Documentation

(back to top)

Roadmap

• Simple web interface to create and manage links.
• Custom link expiration.
• Custom link statistics.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Joshua Schmitt - @jqshuv - me@jqshuv.com

Project Link: https://github.com/jqshuv/short

(back to top)

Acknowledgments

• Cloudflare and GitHub for the amazing services.
• Best-README-Template for the README template.
• Cloudflare Worker - Status Page for the actions workflow inspiration.
• YAML Update Action for the actions workflow tools.
• Bump.sh for the API documentation platform.
• Contrib.rocks for the contributors badge.
• Shields.io for the badges.
• API-Fiddle for the API documentation generation.
• Cloudflare Workers SDK for the SDK and inspiration for code structure.
• Devin's Badges for the badges and inspiration for the logo and banner.
• And of course, the amazing open-source community! 🚀

(back to top)

Legal

• Cloudflare, the Cloudflare logo, Cloudflare Workers® adn the Cloudflare Workers® logo are registered trademarks of Cloudflare, Inc. in the United States and other countries.
• GitHub, GITHUB, the GitHub logo(s), and the GitHub Actions logo are registered trademarks of GitHub, Inc. in the United States and other countries.

Me and this project are not affiliated with Cloudflare, Inc. or GitHub, Inc. in any way. The use of the trademarks is only for identification and explanation purposes. The use of the trademarks does not imply any endorsement by the trademark owners. If you have any questions or concerns, please contact me at me@jqshuv.com. I do not claim any ownership of the trademarks. All rights belong to their respective owners. Thank you for your understanding.

(back to top)