Remix + Deno + Rust -> Webassembly - The Air Metal Stack

Welcome to the Air Metal Stack for Remix! 🦕 + 🦀 This stack is a good choice if you want to run on Deno, deploy to Deno Deploy, and use Rust compiled to WASM for certain functions.

This is a monorepo, with a package for Rust compiled to WASM called rust_functions, and a package for your Remix app called remix-app. Both of these get built using Turborepo.

There is a demo where you can see WASM running both on the worker via an action and on the client with an alert popup.

For more, check out the Remix docs, the wasm-pack docs, and the Rust page.

Install

npx create-remix@latest --template benwis/air-metal-stack

Managing dependencies

Read about how we recommend to manage dependencies for Remix projects using Deno.

• ✅ You should use npm to install NPM packages

  npm install react

  import { useState } from "react";

• ✅ You may use inlined URL imports or deps.ts for Deno modules.

  import { copy } from "https://deno.land/[email protected]/streams/conversion.ts";

• ❌ Do not use import maps.

Setting Up Rust

1. Install the Rust language and it's associated tools. You only need to run this once, as it installs globally. If you already have Rust installed, you can skip this step.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Install wasm-pack to wrap your compiled WASM code in a TS wrapper. The command for Mac and Linux is below. If you're on Windows, visit this link for an exe. You only need to run this once, as it installs globally. If you already have wasm-pack installed, you can skip this step.

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

If you have issues with a lack of precompiled binaries for your platform(on an M1 Mac for example), you can just have cargo compile and install it with the below command.

cargo install wasm-pack

3. Install cargo-watch to allow the Rust code to compile on changes in dev mode

cargo install cargo-watch

Development

From your terminal in the project root:

npm run build
npm run dev

This starts your app in development mode, rebuilding TS and Rust assets on file changes.

Type hints

This template provides type hinting to VS Code via a dedicated import map.

To get types in another editor, use an extension for Deno that supports import maps and point your editor to ./.vscode/resolve_npm_imports.json.

For more, see our decision doc for interop between Deno and NPM.

Production

First, build your app for production:

npm run build

Then run the app in production mode:

npm start

Deployment

Building the Deno app (npm run build) results in two outputs:

• packages/remix-app/build/ (server bundle)
• packages/remix-app/public/build/ (browser bundle)
• packages/rust_functions/build/browser (WASM browser bundle)

You can deploy these bundles to any host that runs Deno, but here we'll focus on deploying to Deno Deploy.

Setting up Deno Deploy

1. Sign up for Deno Deploy.

2. Create a new Deno Deploy project for this app.

3. We use a Github Action to deploy our project's build artifacts to Deno Deploy. To enable this functionality, you must go to your project's settings in Deno and link your Github repo in manual mode.

4. Add a DENO_ENV environment variable to your Deno Deploy project with a value of production. This allows us to know when we're running in production and correctly resolve the path to the WASM files.

Deploying to Deno Deploy

After you've set up Deno Deploy, simply push to your Github repo. It should push your changes over to Deno Deploy. Check the Action in your Github Account, or the Deno Deploy project page for confirmation

Changing Things

• If you'd like to change the name of the Rust crate, be careful to change it in the following places
  • packages/remix-app/server.ts
  • packages/remix-app/routes/rust-demo.tsx
  • packages/remix-app/entry.client.tsx
  • packages/remix-app/entry.server.tsx
  • packages/remix-app/package.json

Notes

• Remix assumes that the public, build, and rust_functions folders will be in the root of the project on Deno Deploy. Changing that structure may lead to errors in production. Caution is advised.