No server-side hosting, serverless cloud functions, or database necessary. Suri static sites can be deployed to Vercel, Netlify, and more (usually for free) in a few minutes.
Suri doesn't care about "technically superior" 3xx server redirects. Suri just
wants you to finally use that domain you spend $59/year on and take back your
short links from the Bitlys and TinyURLs of the web.
https://surishort.link/gh ⇒ https://github.com/surishortlink/suri
https://surishort.link is an example site that showcases Suri in action. You can check out the repository for the site and the file that manages the links to see how it works.
Suri has template repositories that make it super easy to get started. Choose the platform you're deploying to and follow the step by step instructions:
Not deploying to one of those platforms? No worries. Here are a few generic options that cover most other scenarios, whether that's a different cloud provider or hosting it yourself:
At the heart of Suri is the links.json file, located in the src directory,
where you manage your links. All of the template repositories include this file
seeded with a few examples:
{
"/": "https://www.youtube.com/watch?v=CsHiG-43Fzg",
"1": "https://fee.org/articles/the-use-of-knowledge-in-society/",
"gh": "https://github.com/surishortlink/suri"
}It couldn't be simpler: the key is the "short link" path that gets redirected,
and the value is the target URL. Keys can be as short or as long as you want,
using whatever mixture of characters you want. / is a special entry for
redirecting the root path.
Suri ships with a suri executable file that generates the static site from the
links.json file. The static site is output to a directory named build.
All of the template repositories are configured with a build script that
invokes this executable, making the command you run simple:
npm run buildWhen you make a change to the links.json file, simply re-run this command to
re-generate the static site, which can then be re-deployed. Many of the
platforms that Suri has template repositories for are configured to do this
automatically.
Configuration is handled through the suri.config.json file in the root
directory. There is only one option at this point:
| Option | Description | Type | Default |
|---|---|---|---|
js |
Whether to redirect with JavaScript instead of a <meta> refresh. |
Boolean | false |
Finally, any files in the public directory will be copied over to the build
directory without modification when the static site is built. This can be useful
for files like favicon.ico or robots.txt (that said, Suri provides sensible
defaults for both).
If you previously forked/cloned this repository when it was on version 0.1 through 0.5.1, you'll notice a few differences now with version 1.
Version 1 solves three main issues with version 0:
- Difficult to update. Since you forked/cloned this repository in v0, you had to manually merge in upstream changes if you wanted the latest version. This often led to merge conflicts and wasn't an easy, intuitive process most of the time. v1 fixes this by turning Suri into a proper npm package that you can update just like any other dependency.
- Lots of unnecessary files. v0 included deployment and config files for
every platform you could deploy to (Vercel, Netlify, etc.). Even if you
deployed to Vercel, you still had
render.yamlfor Render andapp.jsonfor Heroku (among others) in your repository. v1 fixes this by having separate template repositories for each platform, which only include the necessary files for that platform. - Eleventy was overkill. v0 was built on it for static site generation. While a great option for most static sites, it was overkill for the tiny HTML page that Suri generates. Eleventy came with 34 of its own dependencies, which ultimately resulted in 241 total dependencies being installed. v1 fixes this by removing Eleventy in favor of a purpose-built static site generator that doesn't require a single dependency.
So, how do you upgrade? If you only ever edited your links.json file,
upgrading is simple:
- Create a new repository based on the template repository for your platform (see links above).
- Copy over your
links.jsonfile. - If you changed any of the files in your
publicdirectory, copy those over. - If you set the environment variable
SURI_JSto1, changejstotrueinsuri.config.json.
If you edited any of the Eleventy files – such as the links.njk template – you
probably just want to stick to v0 and continue using Eleventy.
There are a few other noteworthy changes in v1 beyond that:
- The static site is now output to a directory named
buildinstead of_site. - Configuration is now done through the
suri.config.jsonfile instead of environment variables. - Node.js >= v18 is now required, up from v14, which has reached end-of-life.
- Removed
npm run cleanto delete the build directory.npm run builddoes this automatically before each new build. Otherwise, you can manually add it back if you found it useful. - Removed
npm run devto build, watch, and serve the static site during development. It's overkill for the tiny HTML page that Suri generates. - Removed
npm run lintto lint with Prettier. You can manually add it back if you found it useful. - Removed
npm run releaseto release a new version of Suri. You can manually add it back if you want to tag release versions of your repository. - Removed Heroku as a deploy platform because they no longer offer a free tier. You can still deploy there quite easily if you're willing to pay.
- This repository moved from my personal
jstaytonuser on GitHub to a newsurishortlinkorganization for all Suri-related repositories.
The only prerequisite is a compatible version of Node.js (see engines.node in
package.json).
Install dependencies with npm:
npm installThe built-in Node.js test runner and assertions module is used for testing.
To run the tests:
npm testDuring development, it's recommended to run the tests automatically on file change:
npm test -- --watchJSDoc is used to document the code.
To generate the docs as HTML to the (git-ignored) docs directory:
npm run docsPrettier is setup to enforce a consistent code style. It's highly recommended to add an integration to your editor that automatically formats on save.
ESLint is setup with the "recommended" rules to enforce a level of code quality. It's also highly recommended to add an integration to your editor that automatically formats on save.
To run via the command line:
npm run lintWhen the development branch is ready for release,
Release It! is used to orchestrate
the release process:
npm run releaseOnce the release process is complete, merge the development branch into the
main branch, which should always reflect the latest release.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent