DEV Community: arctic_hen7

Introducing Perseus for Rust Web Development!

arctic_hen7 — Sun, 05 Sep 2021 04:35:33 +0000

Perseus is a high-level web development framework for Rust, with full support for SSG and SSR. It's based on Sycamore (a VDOM-less reactivity system for Rust) and adds higher-level functionality, including an Actix Web integration and even a CLI to make development easier!

framesurge / perseus

A state-driven web development framework for Rust with full support for server-side rendering and static generation.

Perseus

Perseus is a blazingly fast frontend web development framework built in Rust with support for generating page state at build-time, request-time, incrementally, or whatever you'd like! It supports reactivity using Sycamore, and builds on it to provide a fully-fledged framework for developing modern apps.

📕 Supports static generation (serving only static resources)
🗼 Supports server-side rendering (serving dynamic resources)
🔧 Supports revalidation after time and/or with custom logic (updating rendered pages)
🛠️ Supports incremental regeneration (build on demand)
🏭 Open build matrix (use any rendering strategy with anything else)
🖥️ CLI harness that lets you build apps with ease and confidence
🌐 Full i18n support out-of-the-box with Fluent
🏎 Lighthouse scores of 100 on desktop and over 95 on mobile
⚡ Support for hot state reloading (reload your entire app's state after you make any code changes in development, Perseus is the only framework in the world that…

View on GitHub

Why?

Since switching from JavaScript to Rust, I've found that there's a distinct lack of a framework in Rust that supports SSR and SSG. Very few even support one. That's where Perseus comes in, with support for SSG, SSR, revalidation, and even incremental generation. In a nutshell, Perseus aims to support all the rendering strategies of NextJS, but in WASM.

Documentation

You can find Perseus' API documentation here and the book, which explains every feature in detail, here.

I've also written a multi-part tutorial on setting up a basic app with Perseus here, which explains everything from installation to serving!

Project Status

Right now, Perseus is still in its early stages, but I hope that it will help people to build lightning-fast apps in Rust using rendering strategies that, up until now, have only been available to JavaScript developers.

Final Words

When I first started out with React many years ago, I had the thought of building my own framework, which I quickly dismissed as foolish, I had everything I needed. But in Rust, we don't yet have everything we need to build awesome web apps, and so Perseus was born to try to solve that problem. Any feedback would be greatly appreciated!

How to set up Tailwind CSS with Yew and Trunk

arctic_hen7 — Sat, 10 Jul 2021 02:06:33 +0000

Yew is a fantastic tool for building web apps with Rust using WASM, though it has very little support for good CSS systems right now. This post will explain how to set up TailwindCSS with Yew and Trunk to create a fully-functional WASM set up with excellent CSS!

Note that this tutorial assumes you have a basic app already set up with Yew and Trunk. If not, check out Yew's official guide to building a starter app here.

Installing Things

We'll use the Tailwind CLI to set things up, which we'll install as a global npm or yarn dependency.

If you are religiously against installing such JavaScript evils on your sacred system, try tailwind-yew-builder, it does very similar things in Docker so you don't have to pollute your computer!

You can install the Tailwind CLI like so:

npm i -g tailwindcss

yarn global add tailwindcss

Now run a sanity check:

tailwindcss --help

You should see the help page for the Tailwind CLI! If not, make sure you've set up your PATH properly for global installs by either NPM or Yarn (particularly Yarn...).

Setting up Tailwind

What we're aiming to get is a single CSS file that we can include in our Trunk HTML. We can do this by running this in the same directory as our top-level index.html for Trunk:

tailwindcss -o ./tailwind.css

That will generate a file named tailwind.css that contains around 4MB of pure CSS. We'll come back to cutting that down. For now though, you should make sure that doesn't get added to version control by adding it your .gitignore like so:

tailwind.css

Now it's time to include that file in our index.html, which we can do by adding this to the head:

<link data-trunk href="./tailwind.css" rel="css" />

This directs Trunk to use the Tailwind file as a stylesheet. You can now use styles in your Yew html!, try it out like this:

html! {
    <p class=classes!("bg-red-100")>{"Test!"}</p>
}

Now is you run trunk serve, you should see a paragraph saying Test with a very light red background! Congratulations, you've set up Tailwind with Yew in development!

Going to production

This is all well and good, but we do NOT want to be serving 4MB of assets to our users! Tailwind has an inbuilt feature for purging unused CSS classes, which it does by searching for the classes you've used. It does that using a regular expression, which just analyses the file, meaning Rust is fine!

Create a tailwind.config.js file at the root of your project and add this to it:

module.exports = {
    purge: {
        mode: "all",
        content: [
            "./src/**/*.rs",
            "./index.html",
            "./src/**/*.html",
            "./src/**/*.css",
        ],
    },
    theme: {},
    variants: {},
    plugins: [],
};

You can add any other Tailwind configuration you might have in here as well. All this does though is instruct Tailwind to look at all Rust, HTML, and CSS files in src/ and remove any classes it doesn't find being used there. We also check index.html in case you have anything in there. This check could probably be refined using the extract property so it only checks Rust files in html!, but this is good enough for now.

Now try building Tailwind for production by running this:

NODE_ENV=production tailwindcss -c ./tailwind.config.js -o ./tailwind.css --minify

That will automatically enable purging, and now check the size of the tailwind.css file. It should be something like 3KB! That's a pretty giant improvement!

Bonus: command aliases

These commands are pretty long and tedious to execute regularly, so you might want to use something like Bonnie to alias them to shorter commands like build and run. Check out the Bonnie wiki for an explanation of how this example file works (should be pretty self-explanatory though):

version="0.3.1"

[scripts]
## Builds Tailwind CSS for development (no purging)
build-tailwind-dev = [
    "cd frontend",
    "tailwindcss -c ./tailwind.config.js -o ./tailwind.css"
]
## Builds Tailwind CSS for production (maximum purging and minification)
build-tailwind-prod = [
    "cd frontend",
    "NODE_ENV=production tailwindcss -c ./tailwind.config.js -o ./tailwind.css --minify"
]
## Builds Tailwind CSS for development usage
setup.subcommands.tailwind = "bonnie build-tailwind-dev"
setup.subcommands.prompt-tailwind = "echo \"Have you installed the Tailwind CLI globally with 'npm i -g tailwindcss' or 'yarn global add tailwindcss'?\""
setup.order = """
tailwind {
    Failure => prompt-tailwind
}
"""

## Builds everything
build.cmd = "cargo build"
## Builds the frontend
build.subcommands.frontend = [
    "cd frontend",
    "bonnie build-tailwind-prod",
    "cargo build"
]
## Runs the frontend, watching for changes (uses Trunk)
## Tailwind is assumed to be set up after `setup`
run.subcommands.frontend = [
    "cd frontend",
    "trunk serve"
]

Then anyone starting out with your project can just run bonnie setup to build Tailwind for them! Running bonnie run frontend will spin up a Trunk server for you automatically, and bonnie build frontend will build everything for production (including Tailwind)! Note that this configuration assumes you've got everything in frontend/ in case you've got a backend/ as well (if not you can just remove those bits).

Full disclosure: I am the maintainer of Bonnie.

Closing words

Hopefully, you now have a working setup with TailwindCSS and Yew! As always, any feedback would be greatly appreciated!

Happy coding!

Serverless GraphQL in Rust with Diana

arctic_hen7 — Fri, 09 Jul 2021 01:52:03 +0000

arctic-hen7 / diana

A Rust GraphQL system with full support for subscriptions and authentication that works out of the box.

Diana

Pragmatic GraphQL that just works.

Book • Crate Page • API Documentation • Contributing

Diana is a GraphQL system for Rust that's designed to work as simply as possible out of the box, without sacrificing configuration ability. Unlike other GraphQL systems, Diana fully supports serverless functions and automatically integrates them with a serverful subscriptions system as needed, and over an authenticated channel. GraphQL subscriptions are stateful, and so have to be run in a serverful way. Diana makes this process as simple as possible.

Diana's documentation can be found in the book.

Installation

Getting started with Diana is really easy! Just install it by adding this to your Cargo.toml file:

diana = "0.2.9"

Due to the complexity of its components, Diana does have a lot of dependencies, so you may want to go and have a cup of tea while you wait for the installation…

View on GitHub

A while ago, I was thinking about how to get serverless GraphQL working with subscriptions. Unfortunately, you can't easily, because subscriptions are state*ful*, and so they have to be run on a server*ful* system. But there's nothing to stop a serverful subscriptions system from being connected to a serverless queries/mutations system!

Diana is a GraphQL system for Rust that does just this. It's mostly a high-level wrapper around the excellent work of async_graphql, but it adds authentication and a bridge between serverful and serverless systems.

Right now, Diana supports integration with Actix Web and AWS Lambda (including derivatives like Netlify) out of the box, with support for more platforms coming soon! You can read Diana's documentation in the book.

Installation

You can easily install Diana by adding this to your Cargo.toml under [dependencies]:

diana = "0.2.3"

All Diana's integrations (currently diana-actix-web and diana-aws-lambda) are kept to the same version as the core library, so everything is always at the same version.

Usage

Diana is pretty easy to use, just define your configuration and set up the integration and you're good to go, with authentication built-in! There's more on how to do this in the docs here.

Closing Words

I've found Diana to be really useful so far for simplifying GraphQL in my own projects, so I hope it helps someone! Please open an issue on the repository if you find a bug or want to propose a new feature!

Command Aliases with Superpowers to Replace Make (Announcing Bonnie v0.3.0)

arctic_hen7 — Fri, 09 Jul 2021 01:09:54 +0000

arctic-hen7 / bonnie

Simple, cross-platform, and fast command aliases with superpowers.

Bonnie

Simple, cross-platform, and fast command aliases with superpowers.

Documentation • Releases • Contributing

Bonnie is a command aliasing tool that allows you to quickly and efficiently define short aliases for long commands that you have to repeatedly run. Here's a quick feature overview:

Supports simple key-value aliasing
Supports inserting custom arguments into commands
Supports interpolating environment variables
Supports adding any and all arguments given into a single place
Supports using different commands on different operating systems
Supports specifying custom shells for individual commands
Supports specifying default shells for different operating systems on a per-file basis
Supports infinitely nestable subcommands
Supports subcommands executed in a certain order based on their exit codes
Supports caching large config files after they've been parsed for performance
Supports initializing new config files from templates

Basically, if you have commands that you routinely run in a project, Bonnie is for you. Bonnie has support for…

View on GitHub

Let's talk about command aliases, making short commands to reference longer ones. What tool springs to mind for you? If you're a JavaScript developer, probably NPM or Yarn scripts, which have such features inbuilt. If you use any other language, Make is probably at the top of the list.

For a very long time, there have been very few dedicated command aliasing tools, and yet build commands get more and more complex! Make was designed as a full build tool, though it's regularly used for simple command aliasing, which is absolute overkill! Not only is Make old and clunky, using it for command aliasing is like using a sledgehammer to crack an egg!

Make works well for command aliasing, but we can do better. Make is great for what it was designed for, don't get me wrong, but that was not simple command aliasing. And yet without Make, we have basically no real solutions though to command aliasing on a per-project basis (sure you can define global aliases in ~/.bash_aliases, but they don't help for multiple different projects).

Enter Bonnie, a tool I built a while ago while I was learning Rust. Since then, I've used Bonnie every day to manage my own command aliases, and it's recently undergone significant changes.

Now, Bonnie supports everything from simple key-value command aliasing to nested subcommands, it has a miniature programming language inbuilt that allows you to specify control flow between commands, and it even supports running different commands on different operating systems, the holy grail of cross-platform collaboration.

Bonnie also has extensive documentation and pre-built binaries on its releases page for Linux, MacOS, Windows, and even musl (for Alpine Linux and the like).

The rest of this post will be a brief tutorial on how to use Bonnie to make command aliasing dead simple in your projects.

Installation

Head over to the releases page and download the latest binary for your OS.
Move that binary to somewhere from which you can execute it easily (e.g. /usr/local/bin on Linux).
Run bonnie -v as a sanity check in the terminal.

Setup

Go into a project that needs command aliasing.
Run bonnie -i.

Congratulations! You now have a super-basic Bonnie configuration in that directory in bonnie.toml. It's written in TOML, which is designed to be a human-readable version of JSON and YAML that doesn't sacrifice features.

Alias time

Let's say you have a really long build command. But, it's the same every time you run it, and it works on every OS. Easy.

version = "0.3.0"

[scripts]
build = "long command here"

How about a multistage command for deploying to a platform like Netlify? Easy.

version = "0.3.0"

[scripts]
deploy = [
    "stage 1",
    "stage 2"
]

Well what about an execution command that needs to do different things on different OSes? Still easy.

version = "0.3.0"

[scripts]
run.generic = "generic fallback here"
run.targets.windows = "windows command here"
run.targets.macos = "macos command here"
run.targets.linux = "linux command here"
# iOS, Android, OpenBSD, FreeBSD, NetBSD, Dragonfly...

Need to depend on some environment variables and user-given arguments? Still easy.

version = "0.3.0"

[scripts]
run.cmd = "execution command here with %ENV_VAR and %arg1"
run.args = [ "arg1" ]
run.env_vars = [ "ENV_VAR" ]

How about adding all the arguments a user gives into one place? Even easier, just use %%.

version = "0.3.0"

[scripts]
run = "execution command here with %%"

What if you've got multiple subprojects to build and you want to do it in a certain order with fallbacks? Bit long, but still easy.

version = "0.3.0"

[scripts]
build.subcommands.frontend = "build command here"
build.subcommands.backend = "build command here"
build.subcommands.update = "recovery command here"
build.order = """
frontend {
    Success => backend {
        Failure => update {
            Success => backend
        }
    },
    Failure => update {
        Success => frontend {
            Success => backend {
                Failure => update {
                    Success => backend
                }
            }
        }
    }
}
"""

Yeah, you can do that. Take a look at the docs for more, like taking user arguments, inserting environment variables, and using custom execution shells! All the examples above can be combined in just about any way you can think of!

Closing words

Bonnie is a command aliasing tool with straight-up superpowers, and I honestly think it can replace just about every use-case of Make for command aliasing. I strongly encourage you to try it out! Any suggestions are more than welcome, and please open an issue if you find any bugs or want to suggest some more features!

Setting up ZSH in Docker

arctic_hen7 — Sat, 17 Apr 2021 06:28:38 +0000

I love ZSH. I love my colorful terminal prompts, I love my indicators, I love my icons. That's all very well on my computer, but what about inside Docker containers?

Well, turns out it's actually really easy to set up ZSH in Docker, it just requires a bit of doing. This post will explain how to do just that! I'll use a non-root user because that's safer, but if you want to use root to do everything, just ignore the user switching and permissions changing, it should all work fine.

I've set this up as a multi-stage build layer, but you can get rid of the AS setup in the first line if you want to do something else.

TL;DR: Here's the Gist! (If you're using NodeJS, there's a special one for you here!)

Let's break that down. We start off by using the Alpine Linux image, but this should work for any Linux image, you might just need to modify apk add to be apt install or something else. If you're using NodeJS in Docker, use node:14-alpine instead.

FROM alpine:latest AS setup

Then we set the environment variable RUNNING_IN_DOCKER to true. I do this with all my Dockerfiles just because it's sometimes really useful to be able to tell easily if a script is running in Docker or on the host (e.g. testing automatically before a commit made in the container vs through VS Code on the host).

ENV RUNNING_IN_DOCKER true

Next, we create a new unprivileged user called main for security (using -D to not give a password). Then we just create a a folder to put our app in, and give ownership of it to that user.

RUN adduser -D main
RUN mkdir -p /app \
    && chown -R main:main /app

if you're using NodeJS, don't bother creating a new user, you already have the node user created for you by the NodeJS base image. That user also already has the setup to install packages without any extra config. Just get rid of the first line and change main:main to node:node.

After that, we install the dependencies for ZSH and then download Antigen (used for managing ZSH plugins) from GitHub.

RUN apk --no-cache add zsh curl git
RUN mkdir -p /home/main/.antigen
RUN curl -L git.io/antigen > /home/main/.antigen/antigen.zsh

With Antigen installed, we copy over our ZSH configuration, which I like to store in .dockershell.sh, but it will be copied to .zshrc in the container. I have an example configuration in this Gist if you need inspiration!

COPY .dockershell.sh /home/main/.zshrc

Then we just give the main user ownership of both the Antigen config and .zshrc.

RUN chown -R main:main /home/main/.antigen /home/main/.zshrc

Now, we can actually run ZSH, which will automatically pull everything we need to fulfill our configuration! This may take some time depending on how complex your config is, but after you've done it once, it's the same for every other container that ever uses it! Also note that you will have to rebuild whenever you change your ZSH config of course. Anyway, we run ZSH as the main user so it sets it up with the right permissions (that's the user we'll interact with the container with). After that, we switch back to root for any remaining stages.

USER main
RUN /bin/zsh /home/main/.zshrc
USER root

And that'll give you ZSH in Docker! Just remember to add this when you want a prompt:

ENTRYPOINT [ "/bin/zsh" ]

Here are three Gists that might help in getting everything operational:

Thanks for reading! Happy ZSHing! 👋

An Alternative to NPM and Yarn Scripts - Bonnie!

arctic_hen7 — Tue, 13 Apr 2021 00:19:49 +0000

arctic-hen7 / bonnie

Simple, cross-platform, and fast command aliases with superpowers.

Bonnie

Simple, cross-platform, and fast command aliases with superpowers.

Documentation • Releases • Contributing

Bonnie is a command aliasing tool that allows you to quickly and efficiently define short aliases for long commands that you have to repeatedly run. Here's a quick feature overview:

✨ Supports simple key-value aliasing
✨ Supports inserting custom arguments into commands
✨ Supports interpolating environment variables
✨ Supports adding any and all arguments in a single place
✨ Supports using different commands on different operating systems
✨ Supports specifying custom shells for individual commands
✨ Supports specifying default shells for different operating systems on a per-file basis
✨ Supports infinitely nestable subcommands
✨ Supports subcommands executed in a certain order based on their exit codes
✨ Supports caching large config files after they've been parsed for performance
✨ Supports initializing new config files from templates
✨ Supports global template
✨ Supports debug mode
✨ Supports…

View on GitHub

Over the last two weeks, I've been moving away from NodeJS and the JavaScript ecosystem to a great extent, mostly because I think the JavaScript world has blown itself out of proportion. To make a basic, performant, modern app, you now need to spend at least a day on proper boilerplate. The number of frameworks has grown exponentially, and I think the ecosystem is just flooded.

So, I decided to try out Elm, a functional programming language with no runtime errors (yes, only compile-time errors). It's fantastic! However, Elm is not designed for the backend, so I decided to finally learn Rust, something I've been meaning to do for about a year now.

Having adopted these two new languages, I found myself wanting a good system to shorten commands for me - like NPM or Yarn scripts. Make was the most obvious option, but it feels somewhat overkill for essentially an aliasing system. Makefiles also have their own syntax, which, although miniscule, was not something I had any desire to delve into. Instead, I decided my first Rust project would be a replacement for NPM and Yarn scripts - Bonnie!

Bonnie is a super-fast command aliasing tool designed to replace NPM or Yarn scripts entirely. You can define simple commands like so:

[scripts]
greet = "echo Hello World"

And then run them like this:

bonnie greet

You can mimic the default behavior of NPM and Yarn scripts, to append any given arguments to the end of the command, by adding the double percent sign (%%) to the end of the command:

[scripts]
greet = "echo Hello %%"

And you can add arguments to the end easily when you run it:

bonnie greet Donald Knuth in math-land

You can even add specific arguments for aliases to take:

[scripts]
greet.cmd = "echo Hello %firstname %lastname"
greet.args = [
    "firstname",
    "lastname"
]

And those can be run like so:

bonnie greet Donald Knuth

Bonnie will gracefully tell you when you've done something wrong, like provided too few arguments, or used invalid syntax in your config file. By default, that config is stored at bonnie.toml, but you can specify an alternative path by setting the BONNIE_CONF environment variable.

This is my first ever CLI, and it's also the first time I've used GitHub Actions to automate building my code on different OSes! Bonnie has binaries available for Linux, MacOS, and Windows on the releases page.

I think Bonnie has been a great opportunity for me to dive into a complex language like Rust head-first, because no matter how long you spend poring over the Rust Book (about 7 hours in my case), you can never learn programming without actually building something. In the particular case of Rust, you can never get your head around lifetimes without actually building something!

I'm using Bonnie daily now, and so far it's working really well! I'm not aware of any alternatives to NPM and Yarn scripts that are as simple as Bonnie, and I hope this will help some people!