Project setup

This article is a walk-through of creating a Twitter clone with Rakkas, a bleeding-edge React framework powered by Vite. Our Twitter clone, which we'll call ublog, is going to:

• Run on Cloudflare Workers,
• store its data on Cloudflare Workers KV,
• and use GitHub for authentication.

Project setup

⚠️ Rakkas itself works on Node 14.20 or later but we'll need at least Node 16.7 for this tutorial

We'll use the create-rakkas-app package to create our boilerplate. The following options will enable all features except the demo app:

npx create-rakkas-app@latest ublog -y --no-demo

The second step is to change into the project directory and install dependencies:

cd ublog && npm install

At this point we should do a quick check to make sure everything was set up properly by launching a dev server:

npm run dev

This will start a dev server on localhost:5173. You can visit that address to see the "Hello World" message.

Now you can edit the file src/routes/index.page.tsx to see Rakkas's hot module reloading with fast refresh support in action. Your edits will be reflected instantly in the browser.

Customization

The package name in the package.json file is -TODO- to remind us that it should be changed. So we'll go ahead change it to ublog.

The generated boilerplate comes with a .prettierrc file for configuring Prettier, a popular code formatter. The generated configuration is empty but I like customizing it a little to use tabs for indentation by adding "useTabs": true. You can have your own preferences of course. After editing, we'll run the following command to reformat our sources:

npm run format

Now we should create a .gitignore file and add node_modules and dist to it:

node_modules
dist

...and initialize our Git repo:

git init && git checkout -b main

Setting up for Cloudflare Workers

Rakkas documentation on Cloudflare Workers says we should create a wrangler.toml file. This is copied verbatim from there except the project name:

name = "ublog"
compatibility_date = "2021-11-01"
compatibility_flags = [
  "streams_enable_constructors",
]
main = "dist/server/cloudflare-workers-bundle.js"
usage_model = 'bundled'
workers_dev = true

[site]
bucket = "./dist/client"

Then we should install the HatTip adapter for Cloudflare Workers. HatTip is a set of JavaScript libraries for building HTTP server applications that run on many platforms like Node.js, Cloudflare Workers, Vercel, Netlify, Deno, and more. Rakkas relies on it for serverless support.

npm install -S @hattip/adapter-cloudflare-workers

Now we'll configure Rakkas to build for Cloudflare Workers by updating the options passed to Rakkas Vite plugin in the vite.config.ts file. It will look like this in the end:

import { defineConfig } from "vite";
import rakkas from "rakkasjs/vite-plugin";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
    plugins: [
        tsconfigPaths(),
        rakkas({
            adapter: "cloudflare-workers",
        }),
    ],
});

Now we'll see if everything works when we build our application by running npm run build. If everything works well, Rakkas will tell you that it built your Cloudflare Workers bundle in dist/server/cloudflare-workers-bundle.js.

Cloudflare Workers has a local emulator called miniflare. We can use it to test our bundle locally:

npm install -D miniflare
npx miniflare --modules dist/server/cloudflare-workers-bundle.js

This will launch a local worker emulator on localhost:8787. You should see the "Hello World" message when you visit.

Deploying

If everything worked well so far, we can deploy our (as of yet useless) application to Cloudflare Workers using the wrangler CLI. If you don't have a Cloudflare Workers account or if you're not logged in, the following command will open your browser so you can log in or create a free account before publishing your application:

npm install -D wrangler
npx wrangler publish

If everything works well, your application will be up and running on Cloudflare Workers and wrangler will print the URL it's available at. If you go ahead and visit, you should see the "Hello World" message.

Finally, let's create a few shortcuts before committing our changes. Let's add the following to the scripts section of the package.json file:

"scripts": {
    // ... existing scripts ...
    "local": "miniflare --modules dist/server/cloudflare-workers-bundle.js",
    "deploy": "wrangler publish"
}

Now we can simply do npm run local to test locally and npm run deploy to deploy.

We can now commit our changes:

git add . && git commit -m "chore: initialize boilerplate for Cloudflare Workers"

What's next?

In the next article, we'll learn how to use Cloudflare Workers KV to store our data, including how to create a mock KV store in development.

You can find the progress up to this point on GitHub.