A fast, simple, browser shortcut tool.

Table of Contents

1. Pre-Requisites
2. Installation
3. Build
4. Setup
5. Architecture
6. Config
7. FAQ's

1. Pre-Requisites ^{Top ▲}

For this project to run you will require the following:

• Rust & Cargo installed (https://www.rust-lang.org/tools/install)
• pnpm installed (https://pnpm.io/installation)
• SQLite3 installed (https://sqlite.org/download.html)
• [optional] make installed (https://www.gnu.org/software/make/)

2. Installation ^{Top ▲}

This project is built with Cargo, pnpm, and SQLx-cli.

If make was installed, these steps can be skipped with: ^{Skip ▼}

make setup

To set-up the repository install the rust dependencies with:

cargo install
cargo binstall cargo-watch
cargo binstall sqlx-cli

Next install the pnpm dependencies with:

pnpm install

Finally, you will need to create and migrate the db with:

sqlx db create
sqlx migrate run

Or using the bash script:

./migrations.sh

Now you should be ready to build and run the project.

3. Build ^{Top ▲}

The build process is quite simple.

First run:

make tailwind

or

npx @tailwindcss/cli -i ./ui/styles/tailwind.css -o ./ui/assets/main.css

This is required to set-up the css styling for the project.

Following that run:

make server-watch

or

RUST_LOG=info cargo watch -x run

This will start the Rust server. Once built, you can access the app at http://localhost:3000 or your configured port.

4. Setup ^{Top ▲}

Following this you will need to set up a shortcut for your search bar. Given you have not changed the port, the steps for some common browsers are as follows:

Google Chrome/Chromium:

1. Go to chrome://settings/search.
2. Click "Manage search engines and site search".
3. Click "Add" next to "Site search".
4. Fill the url to be http://localhost:8035/api/get?keyword=%s
5. Fill out the rest of the details and save.

Mozilla Firefox:

1. Go to about:preferences#search.
2. Click "Search Shortcut".
3. Click "Add".
4. Fill the url to be http://localhost:8035/api/get?keyword=%s
5. Fill out the rest of the details and save.

Microsoft Edge:

1. Go to edge://settings/searchEngines?search=address.
2. Click "Add" next to "Site search".
3. Fill the url to be http://localhost:8035/api/get?keyword=%s
4. Fill out the rest of the details and save.

Brave:

1. Go to brave://settings/search.
2. Click "Manage search engines and site search".
3. Click "Add" next to "Site search".
4. Fill the url to be http://localhost:8035/api/get?keyword=%s
5. Fill out the rest of the details and save.

Vivaldi:

1. Go to vivaldi://settings/search.
2. Click "Search Engines".
3. Click "Add" next to "Site search".
4. Fill the url to be http://localhost:8035/api/get?keyword=%s
5. Fill out the rest of the details and save.

5. Architecture ^{Top ▲}

This project is a Rust HTMX monolith application.

HTMX is a lightweight HTML templating structure that allows you to swap elements in the DOM through function returns.

For the templating system, we are using Tera, which uses Jinga-inspired templates.

With Tera, we have chosen to use the tera-hot-reload crate. This allows for quick and easy development of the ui.

Roughly a page template can be described like below:

#[derive(TeraTemplate, Serialize)]
#[template(path = "template.html")]
pub struct Template {
  pub title: String
}

pub fn getTemplate(tera: Tera) {
  let context = Template { title: "template" }

  return Html(self.render(tera));
}

Where an example template.html can be:

{% extends "base.html" %}
 
{% block title %}{{ title }}{% endblock %}
 
{% block content %}
<main class="ml-14 pl-5 flex-1 p-4 dark:bg-neutral-800" style="justify-items: center;" >
  <div id="load-error" class="dark:text-white"></div>
  {% include "components/search/search.html" %}
  <div id="results" \>
</main>
{% endblock %}

With api calls, we then set the results div as the target for the output of a function.

More examples of this can be seen in:

• HTMX templates directory
• Rust templates directory
• Routes
• Service

The interaction between our server and our database is sqlx.

In an ideal world, I would use sqlean, spellfix1 extension, or elastic-rs to allow fuzzy searching within the database.

But for simplicity's sake, we are currently using a SQLite database without any extensions.

This means that our searches will require pulling the entire shortcut database and searching/sorting within the Rust layer. This in practice is not as bad as you think due to Rust's fast nature.

Finally, we use tailwind for our component styling.

6. Config ^{Top ▲}

All the config is kept within the .env file.

The default is:

DATABASE_FILENAME=shortcut.db
DATABASE_URL=sqlite://${DATABASE_FILENAME}?mode=rwc
PORT=3000
UI_URL=http://localhost:${PORT}

7. FAQ's ^{Top ▲}

Feel free to create any issues at: https://github.com/AlexTrebs/shortcut/issues