DEV Community: bop

Using Hono with SvelteKit - Full type-safety with RPC

bop — Mon, 29 Jan 2024 19:15:50 +0000

Introduction
Why Hono?
Setup
The Backend
RPC
Building Our Application
- Why not Elysia with Eden?
- Inspiration
- Repository
- What comes next?
Thanks
About the author

Introduction

I fell in love with Svelte and SvelteKit recently and it gave me the fuel I needed to start some personal projects. I was feeling hostage by React and maybe that was ok until I needed some features that only RSC/Next.js was going to give me. That was the Armageddon. After dwelling with some ClojureScript and other FP languages that compile to JS I stumbled on the Svelte community and it was a blast how easy and beautiful it is.

Why Hono?

If you ever used an SSRish framework you know that it has a way to create endpoints within its (probably) file-based routing. Of course, you can also simply inject the data into the route itself using its loaders.

But when trying to fix the problem of invalidation and wanting to get the same data in the same way on the client side you will probably lose some of the type-safety on the params, URL, response, etc.

After using tRPC on Next.js (t3) I've been passionate about the possibility of having end-to-end type-safety + a way to write your data sources not bound to the file-based route and its default APIs.

Hono offers good DX and a blazingly fast library to help you build your backend with native RPC embedded in its code. It has Zod support and it's written with TypeScript with very readable types so you can understand what's happening. It also supports Bun and a bunch of runtimes so you can run it everywhere. Check the documentation! It's also very helpful.

Setup

First we need to scaffold a SvelteKit project using pnpm:

pnpm create svelte@latest sveltekit-hono-playground

I used the following options (but it doesn't matter):

Now let's install hono (and validations dependencies):

pnpm install hono zod @hono/zod-validator

Now let's run the project and keep it running with:

pnpm dev

You should see something resembling the following:

The Backend

Let's focus now on creating some endpoints for us. Please don't get caught up on file placement and structure. Do it however you please and contact me if you fail to place the logic inside your preferred structure and I will try to help you.

./src/lib/api.ts

import { zValidator } from '@hono/zod-validator';
import { Hono } from 'hono';
import { z } from 'zod';

export const Task = z.object({
    id: z.string().uuid(),
    name: z.string().min(1),
    done: z.boolean()
});

export type Task = z.infer<typeof Task>;

export const TaskCreateInput = Task.pick({ name: true });

export type TaskCreateInput = z.infer<typeof TaskCreateInput>;

export const TaskParam = Task.pick({ id: true });
export type TaskParam = z.infer<typeof TaskParam>;

/**
 * This will be our in-memory data store
 */
let tasks: Task[] = [];

export const router = new Hono()
    .get('/tasks', (c) => c.json<Task[]>(tasks))
    .post('/tasks', zValidator('json', TaskCreateInput), (c) => {
        const body = c.req.valid('json');
        const task = {
            id: crypto.randomUUID(),
            name: body.name,
            done: false
        };
        tasks = [...tasks, task];
        return c.json(task);
    })
    .post('/tasks/:id/finish', zValidator('param', TaskParam), (c) => {
        const { id } = c.req.valid('param');
        const task = tasks.find((task) => task.id === id);
        if (task) {
            task.done = true;
            return c.json(task);
        }

        throw c.json({ message: 'Task not found' }, 404);
    })
    .post('/tasks/:id/undo', zValidator('param', TaskParam), (c) => {
        const { id } = c.req.valid('param');
        const task = tasks.find((task) => task.id === id);
        if (task) {
            task.done = false;
            return c.json(task);
        }

        throw c.json({ message: 'Task not found' }, 404);
    })
    .post('/tasks/:id/delete', zValidator('param', TaskParam), (c) => {
        const { id } = c.req.valid('param');
        tasks = tasks.filter((task) => task.id !== id);
        return c.json({ message: 'Task deleted' });
    });

export const api = new Hono().route('/api', router);

export type Router = typeof router;

And to make it work:

./src/routes/api/[...paths]/+server.ts

import { api } from '$lib/api';
import type { RequestHandler } from '@sveltejs/kit';

export const GET: RequestHandler = ({ request }) => api.fetch(request);
export const POST: RequestHandler = ({ request }) => api.fetch(request);

Above you can see the code that redirects the requests made with a URL starting with /api to be handled by Hono. The fetch method can be used in various ways to lift a Hono server including Bun. You can test /api/tasks on the browser you should see an empty JSON array.

RPC

So now let's add the RPC part:

./src/lib/make-client.ts

Please be aware that this part is not as straightforward as the rest. Make sure you give it a good read. I will be explaining it step-by-step on what is happening and why is it happening that way.

import type { Router } from '$lib/api';
import { hc } from 'hono/client';

let browserClient: ReturnType<typeof hc<Router>>;

export const makeClient = (fetch: Window['fetch']) => {
    const isBrowser = typeof window !== 'undefined';
    const origin = isBrowser ? window.location.origin : '';

    if (isBrowser && browserClient) {
        return browserClient;
    }

    const client = hc<Router>(origin + '/api', { fetch });

    if (isBrowser) {
        browserClient = client;
    }

    return client;
};

Now we will be using it like this to load the tasks into our view:

./src/routes/+page.ts

import { makeClient } from '$lib/make-client';
import type { PageLoad } from './$types';

export const load = (async ({ fetch }) => {
    const client = makeClient(fetch);
    const tasks = await client.tasks.$get();

    if (!tasks.ok) {
        return { tasks: [] };
    }

    return {
        tasks: await tasks.json()
    };
}) satisfies PageLoad;

But what about that makeClient monster you made?
Common Reader

The make client needs to be like that because it's being used on the backend and on the browser to bring data to the page.

You can see it receives fetch as a parameter, right? That is because (see ./src/routes/+page.ts) SvelteKit makes a custom fetch available from the backend to us. Of course, on the client side, Hono will be using the default window.fetch while on the backend, it's just not that simple.

That's because, in the backend context, we don't have access to the origin URL, and imagine doing self-requests every time to grab data, that would be not good.

SvelteKit fixes that by giving you a fetch that, before going to the network layer, tries to resolve the request into its handlers, which will fall back into calling what we wrote on ./src/routes/api/[...paths]/+server.ts and if Hono can identify the route, will simply run its handler and return the value, again, skipping the network layer.

You can read more about it if you want.

Also, we are sprinkling some singleton pattern esque to make sure that when creating the client on the browser we don't recreate the client at every usage.

The window.location.origin part is to not break the $url methods on the browser so we can easily invalidate the request on the client side. You can also read more about this.

Building Our Application

Our Task Manager will have only one page. I have added a little progressive enhancement, just for demonstration, by adding use:enhance on the form. And now you can see the whole app:

./src/routes/+page.server.ts

import { TaskCreateInput } from '$lib/api';
import { makeClient } from '$lib/make-client';
import type { Actions } from '@sveltejs/kit';

export const actions = {
    async default({ fetch, request }) {
        const client = makeClient(fetch);
        const form = await request.formData();
        const data = TaskCreateInput.parse(Object.fromEntries(form));
        const response = await client.tasks.$post({
            json: data
        });

        if (!response.ok) {
            return {
                message: 'An error occurred'
            };
        }

        return await response.json();
    }
} satisfies Actions;

./src/routes/+page.svelte

<script lang="ts">
    import { enhance } from '$app/forms';
    import { invalidate } from '$app/navigation';
    import { makeClient } from '$lib/make-client.js';

    export let data;
    const client = makeClient(fetch);

    let isLoading = false;
    let taskName = '';

    async function handleActionClick(id: string, action: `${keyof (typeof client.tasks)[':id']}`) {
        try {
            isLoading = true;
            await client.tasks[':id'][action].$post({
                param: { id }
            });
            await invalidate(client.tasks.$url());
        } catch (error) {
            console.error(error);
        } finally {
            isLoading = false;
        }
    }
</script>

<h1>BTMW: The best task manager in the world</h1>

<div>
    <h2>New Task</h2>
    <form method="POST" use:enhance>
        <input type="text" name="name" required bind:value={taskName} disabled={isLoading} autofocus />
        <button type="submit" disabled={isLoading}>Add</button>
    </form>
</div>

<div>
    <h2>My Tasks</h2>
    {#if data.tasks.length === 0}
        <p>You don't have any tasks! Be free little bird</p>
    {:else}
        <ul>
            {#each data.tasks as task (task.id)}
                <li>
                    {task.done ? '✅' : '⬛️'}
                    {task.name}
                    {#if !task.done}
                        <button type="button" on:click={() => handleActionClick(task.id, 'finish')}
                            >Finish</button
                        >
                    {:else}
                        <button type="button" on:click={() => handleActionClick(task.id, 'undo')}>Undo</button>
                        <button type="button" on:click={() => handleActionClick(task.id, 'delete')}
                            >Delete</button
                        >
                    {/if}
                </li>
            {/each}
        </ul>
    {/if}
</div>

Notice how Hono makes invalidating RPC requests frictionless by giving us the $url method. For every action that can be done on a single task, it invalidates the task list so we can have the updated task list without refreshing the page.

This will give us the following responsive, fast, progressively enhanced, tasty SPA to use as our task manager:

Why not Elysia with Eden?

Elysia and (Eden)[https://github.com/elysiajs/eden] are awesome! I've been trying it and it gives probably the same features as Hono. Maybe some even better DX sometimes. But the lack of Zod support (I don't want to learn a new validation framework), $url method, and running on Bun for now made me choose to focus on Hono.

Inspiration

This article, the Hono docs, Elysia SvelteKit example, trpc-sveltekit and lot's of general reading.

Repository

You can find it here.

What comes next?

Next will be trying to create a post on how and why use @tanstack/query on SvelteKit. Keep in touch!

Thanks

Thank you for reading. Feedback welcome to help me share knowledge effectively.

About the author

Hello there! I'm bop, a dedicated software engineer driven by a love for continuous learning and creative exploration. Stay connected with me for updates on my current activities and exciting projects.

🌐 Website: bop.systems
📧 Email: brunooliveira37@hotmail.com

📱 Social Media:

You can also buy me a coffee to support me, if you like what I do

Neovim users, what AI helpers have you been using besides Copilot?

bop — Fri, 15 Dec 2023 14:13:26 +0000

Us neovim users should surrender to VSCode or other IDE's if we want to use all the Copilot stuff. But maybe I'm missing some other tools! What have you been using besides GitHub Copilot to tune up your IDE?

Adding Dependencies on Clojure Projects the Node Way: A Small Intro to neil CLI

bop — Tue, 28 Nov 2023 15:10:25 +0000

One of the things that I found really hard when starting with Clojure is handling dependencies. I come from a PHP and JS background so composer and npm were the standard to me. I also worked with some Ruby projects, and gem is also cool.

They all have something in common: a way to remove/add dependencies by simply using a command followed by the name of the package. Like in npm:

# latest version
npm install package-name

# specific version
npm install package-name@version

The Clojure Way

If you find yourself trying to add a dependency on a Clojure project you will find yourself having to copy and paste the dependency "token" to a deps.edn or project.clj or the maven way.

If you take a look a this library which is an "official" library you will find three snippets of code for adding the dependency to your project and some with a very strange syntax.

After doing that, the next time you open your project or REPL clojure will download the dependencies for you.

The neil Way

Recently, doing my Clojure repository searching for studying purposes (or CRSSP for short) I stumbled on this very underrated and not much used in tutorial CLI helper for deps.edn Clojure projects called neil.

neil is:

A CLI to add common aliases and features to deps.edn-based projects.

Created by the same guy who created babashka which is a way to write bash scripts, node scripts, and even apple scripts using Clojure. A very proficient and influential developer in the Clojure community. This is how borkduke's neil helps us:

neil add dep com.stuartsierra/component

And done. The dependency was added to deps.edn. Automatization wins again!

Neil is the Way!

So neil has a bunch of other features like project scaffolding, building, testing, adding license, etc. I really recommend you take a deep look at the repository and learn all the automatized possibilities that neil adds to your project.

Thanks!

In closing, I hope this introduction to the neil CLI was helpful in simplifying your Clojure dependency workflow. A big thank you to the developers behind neil for creating a tool that streamlines common tasks. Please feel free to reach out if you have any other questions about using neil in your own projects.

About the Author

🌐 Website: bop.systems
📧 Email: brunooliveira37@hotmail.com

📱 Social Media:

You can also buy me a coffee to support me, if you like what I do

Making shadow-cljs REPL's More Interactive

bop — Tue, 21 Nov 2023 20:00:13 +0000

So, if you ever tried to use some REPL you remember to be able to move your cursor not only sideways but also up and down to go trough some history.

On Clojure, this is very important and if you ever used Clojure's CLI you know that we end up with two executables on our machine: clj and clojure.

What is the difference between them?

So if you run $ clojure or $ clj, both will give you an interactive REPL to use. But they have some different behavior on them. Let's see:

Using clojure

Using clj

As you can see when using clj instead clojure all the interactions you see happen with no problem.

But what's the difference?

Well, clj is using a tool to make it more interactive. This tool is called rwrap.

rwrap stands for "readline wrapper," and it is a utility primarily used to add readline functionality to command-line applications that lack built-in line editing capabilities.

It enhances the user experience by providing features like command history, line editing (such as editing and deleting characters in the input line), and command completion in terminal-based applications that do not inherently support these functionalities.

If we open the clj file we will see something like this:

#!/usr/bin/env bash

bin_dir=/usr/local/Cellar/clojure/1.11.1.1149/bin

if type -p rlwrap >/dev/null 2>&1; then
  exec rlwrap -r -q '\"' -b "(){}[],^%#@\";:'" "$bin_dir/clojure" "$@"
else
  echo "Please install rlwrap for command editing or use \"clojure\" instead."
  exit 1
fi

Which, in other words, it's a script that wraps the clojure cli into rlwrap. Got it?

The thing is that shadow-cljs doesn't have that helper. So, when using any of the available terminal REPL's, like node-repl, it messes up everything and it's very hard to use.

Take a look

What's the solution for this?

Based on the clj script I added to my PATH the cljs script. That does the same thing but tries to find the installed shadow-cljs or fall back to the global one.

That's the final script I've been using:

#!/usr/bin/env bash

local_install=$(realpath ./node_modules/.bin/shadow-cljs)
global_install=/usr/local/bin/shadow-cljs
usable_install=$(if [ -f "$local_install" ]; then echo "$local_install"; else echo "$global_install"; fi)

if type -p rlwrap >/dev/null 2>&1; then
  exec rlwrap -r -q '\"' -b "(){}[],^%#@\";:'" "$usable_install" "$@"
else
  echo "Please install rlwrap for command editing."
  exit 1
fi

I've saved it as cljs on my PATH. And now I can do this:

The end

In this article, we have learned how to improve the interactivity of Shadow CLJS REPLs by adding features like cursor navigation and command history. The solution discussed was to wrap Shadow CLJS in the rlwrap utility, similar to how the Clojure tool clj works. By using a simple script to launch Shadow CLJS through rlwrap, we can now fully enjoy the interactive REPL experience that is crucial for building and testing ClojureScript applications.

Thank you for reading!

Converting JS Libraries to Clojure: Part 1

bop — Mon, 20 Nov 2023 19:02:26 +0000

What are we doing here?

This is a series of articles with two purposes: to improve my Clojure and ClojureScript knowledge and to help JavaScript developers learn Clojure.

The first library we will be transforming is titleize. We are starting with the simplest library I could think I ever used and maybe you used too.

Also because sindresorhus has the largest, high-quality, open-source codebase of reusable js/ts snippets and libraries, I've seen.

The recommendation here is not necessarily to use it in a project but to know the basics of Clojure code that can be used on both Clojure and ClojureScript environments. Maybe if you have a Clojure(Script) project you can install this library, but if you just want a titleize function in your JavaScript code, just npm install the original one.

The titleize function

Let's start by digging into the original code. This is the titleize function. It has no dependencies. A very simple
straightforward JavaScript regex shenanigans. Take a look:

export default function titleize(string) {
    if (typeof string !== 'string') {
        throw new TypeError('Expected a string');
    }

    return string.toLowerCase().replaceAll(/(?:^|\s|-)\S/g, x => x.toUpperCase());
}

So the first thing to do is to create this function. I don't want to spend too much your time so let's just fire a REPL
and start doing stuff there. So run this:

$ clj

So now on the REPL, you can test some code. Run some sum example like (+ 1 2) and make sure you receive 3 and then we
can start.

String functions

So first let's require Clojure's string standard library with the following code.

(require [clojure.string :as string])

In the original code, we can see the author using the toLowerCase and toUpperCase methods from JavaScript's string type. The equivalents in Clojure would be:

(string/lower-case "BEING DEV IS NICE") ; => being dev is nice
(string/upper-case "being dev is cool") ; => BEING DEV IS COOL

Ok. We could also refer to the functions directly.

(require [clojure.string :refer [lower-case upper-case]])

(lower-case "BEING DEV IS NICE") ; => being dev is nice
(upper-case "being dev is cool") ; => BEING DEV IS COOL

Then we can see on the original implementation that we also have a usage of replaceAll with some regex. The
equivalent will also be from clojure.string which is the replace function.

Regex

In Clojure, the regex syntax is a little bit different. Of course, it will depend on the application but for now, we will ignore the modifiers (we can see the /g on the titleize implementation) and just transform that to our beloved clojure syntax:

Original:

/(?:^|\s|-)\S/g

Clojure:

#"(?:^|\s|-)\S"

Not trusting me? Ok. Make sure you know by yourself then:

(type #"") ; => java.util.regex.Pattern

Glueing everything together

Now let's write our function:

(require [clojure.string :refer [lower-case upper-case replace]])

(defn titleize [str]
    (replace (lower-case str) #"(?:^|\s|-)\S" upper-case))

Done! Run the above on your REPL and then you can use it:

(titleize "the quick brown fox jumps over the lazy dog") ; => The Quick Brown Fox Jumps Over The Lazy Dog

Let's refactor it a little

Our code is fine now. It works! But it still doesn't leverage one of the best things Clojure has: macros!

To make our code a little bit more readable and, I would say, better to maintain we will be using the thread first macro. Which can be simply described as:

The thread-first macro -> in Clojure allows you to write code in a more sequential and readable manner by threading the output of one function call into the first argument of the next function call. It simplifies nested function calls by enhancing code readability and reducing the need for intermediate variables. This macro assists in composing functions together in a natural left-to-right order, making the code easier to understand and maintain.

By applying that, our code will now look like this:

(defn titleize [str]
  (-> str
    (lower-case)
    (replace #"(?:^|\s|-)\S" upper-case)))

So pretty! Right? Clojure has a bunch of useful macros.

Tests

The original library has a very simple test chain, comparing a bunch of strings that we have. The repo uses ava to run the tests. Take a look:

import test from 'ava';
import titleize from './index.js';

test('main', t => {
    t.is(titleize(''), '');
    t.is(titleize('unicorns and rainbows'), 'Unicorns And Rainbows');
    t.is(titleize('UNICORNS AND RAINBOWS'), 'Unicorns And Rainbows');
    t.is(titleize('unicorns-and-rainbows'), 'Unicorns-And-Rainbows');
    t.is(titleize('UNICORNS-AND-RAINBOWS'), 'Unicorns-And-Rainbows');
    t.is(titleize('unicorns   and rainbows'), 'Unicorns   And Rainbows');
});

For Clojure we have the clojure.test library so we just need to copy the test and apply it on Clojure syntax:

(ns excelsia.titleize-test
  (:require [clojure.test :refer [deftest is testing]]
            [excelsia.titleize :as titleize]))

(def result-map {"" ""
                 "unicorns and rainbows" "Unicorns And Rainbows"
                 "UNICORNS AND RAINBOWS" "Unicorns And Rainbows"
                 "unicorns-and-rainbows" "Unicorns-And-Rainbows"
                 "UNICORNS-AND-RAINBOWS" "Unicorns-And-Rainbows"
                 "unicorns   and rainbows" "Unicorns   And Rainbows"})

(deftest titleize-test
  (testing "titleize"
    (doseq [[input expected] result-map]
      (is (= expected (titleize/titleize input))))))

Now, I'm not going too deep on that, but you can see on the repository that we are running tests both on the Clojure environment and on the Node.js environment to make sure the code works properly both on Clojure and ClojureScript.

Summary

So we grabbed a very small JS library and ported it to Clojure library compatible with ClojureScript. Tell me your
feedbacks and other small libraries you may want to see converted to Clojure.

Code

https://github.com/excelsia-dev/titleize

What's the simplest way to compile ClojureScript to JS? Like 1 file, no overhead.

bop — Wed, 11 May 2022 22:15:21 +0000