Project setup
Tags: react, cloud
Published: 2022-08-10 08:23:00

This article is a walk-through of creating a Twitter clone with [Rakkas](https://github.com/rakkasjs/rakkasjs), a bleeding-edge React framework powered by [Vite](https://vitejs.dev/). Our Twitter clone, which we'll call **ublog**, is going to:

- Run on [Cloudflare Workers](https://workers.cloudflare.com/),
- store its data on [Cloudflare Workers KV](https://www.cloudflare.com/products/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:

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

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

```bash
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:

```bash
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](https://prettier.io/), 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:

```bash
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](https://rakkasjs.org/guide/cloudflare-workers) on Cloudflare Workers says we should create a `wrangler.toml` file. This is copied verbatim from there except the project name:

```toml
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](https://github.com/hattipjs/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.

```bash
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:

```ts
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:

```bash
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:

```bash
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:

```json
"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:

```bash
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](https://www.cloudflare.com/products/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](https://github.com/rakkasjs/ublog/tree/article-1).