DEV Community: Fatih Aygün

Styling with UnoCSS

Fatih Aygün — Wed, 31 Aug 2022 17:35:58 +0000

Rakkas supports all styling options available to React apps. Since we're building an app with cutting-edge technologies, I think it would be fitting to use some of the latest and greatest styling options. Tailwind CSS seems to be the coolest kid in town nowadays. But we'll go even further and use UnoCSS. It's a reimagining of atomic CSS with an instant on-demand approach that is 200x faster than Tailwind JIT! Let's start by installing the required packages:



npm install -D unocss @unocss/reset

unocss is the main package and @unocss/reset provides a collection of CSS resets, including the Tailwind CSS "Preflight", an opinionated set of base styles for Tailwind.

Following the UnoCSS readme, we add to our vite.config.ts file import Unocss from "unocss/vite"; and then add UnoCSS() the the plugins array:



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

dotenv.config();

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

We also add the following imports at the top of our src/routes/layout.tsx:



import "@unocss/reset/tailwind.css";
import "uno.css";

ESLint will complain about not being able to resolve uno.css. You can shut it up by adding the following to your .eslintrc.cjs file:



    // ...
    rules: {
        "import/no-unresolved": ["error", { ignore: ["uno.css"] }],
    },
};

If you spin up the dev server, you'll see that our app is now completely unstyled. UnoCSS allows us to style our app with class names. Its default preset supports many atomic/functional CSS libraries all at once: ml-3 (Tailwind), ms-2 (Bootstrap), ma4 (Tachyons), and mt-10px (Windi CSS) are all valid.



.ma4 { margin: 1rem; }
.ml-3 { margin-left: 0.75rem; }
.ms-2 { margin-inline-start: 0.5rem; }
.mt-10px { margin-top: 10px; }

I will start by removing the <hr /> element and add some color, padding and a bottom border to our header:



<header className="px-5 py-5 b-b bg-amber">

px is shorthand for horizontal padding and py is shorthand for vertical padding. b-b is shorthand for a bottom border. bg-amber is for setting the background color to amber. You can learn more on the UnoCSS website.

I'm sure everyone reading this article is better at designing a good-looking website than I am. Here's what I could come up with after half an hour of tinkering:

It may not be great but I'm happy with the result. I did change the markup as I've seen fit. I also added a Head component to set the page title in index.page.tsx (<Head title="uBlog" />). You can see the results here.

Conclusion

I hope you enjoyed this tutorial series and also hope that you find Rakkas as easy to work with as I think it is. You can extend this little app by adding user profile pages, post deletion functionality, pagination, and more. Feel free to say hi on Rakkas Discord chat server!

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

Using cookies

Fatih Aygün — Sun, 14 Aug 2022 17:14:00 +0000

In the previous article we managed to sign a user in with GitHub. Now we have to remember the signed-in user. There was also a state parameter that we glossed over that was passed back and forth between our server and GitHub to make sure that the sign-in request was indeed initiated by us, and not by a malicious third party. state is, in effect, a cross-site request forgery prevention token. We'll just generate a random ID and remember it. Cookies are the most common way to remember something in a web application.

As we discussed before, Rakkas relies on HatTip for handling HTTP so we will use the @hattip/cookie package to manage cookies:

npm install -S @hattip/cookie

Then we will add the cookie middleware to our entry-hattip.ts. We'll use the crypto.randomUUID() function to generate our state token but crypto is not globally available in Node. Luckily it is still available in the crypto package under the name webcrypto so we can easily polyifll it:

import { createRequestHandler } from "rakkasjs";
import { cookie } from "@hattip/cookie";

declare module "rakkasjs" {
    interface ServerSideLocals {
        postStore: KVNamespace;
    }
}

export default createRequestHandler({
    middleware: {
        beforePages: [
            cookie(),
            async (ctx) => {
                if (import.meta.env.DEV) {
                    const { postStore } = await import("./kv-mock");
                    ctx.locals.postStore = postStore;

                    // Polyfill crypto
                    if (typeof crypto === "undefined") {
                        const { webcrypto } = await import("crypto");
                        globalThis.crypto = webcrypto as any;
                    }
                } else {
                    ctx.locals.postStore = (ctx.platform as any).env.KV_POSTS;
                }

                // We'll add more stuff here later
            },
        ],
    },
});

The cookie middleware makes things like ctx.cookie and ctx.setCookie available in our server-side code. So now we can generate our random state token and put it in a cookie at the spot we marked with "We'll add more stuff here later" comment:

if (!ctx.cookie.state) {
    const randomToken = crypto.randomUUID();
    ctx.setCookie("state", randomToken, {
        httpOnly: true,
        secure: import.meta.env.PROD,
        sameSite: "strict",
        maxAge: 60 * 60,
    });

    // To make it immediately available,
    // We'll store it here too.
    ctx.cookie.state = randomToken;
}

Now we can use the cookie value instead of our 12345 placeholder in src/routes/layout.tsx:

const {
    data: { clientId, state },
} = useServerSideQuery((ctx) => ({
    clientId: process.env.GITHUB_CLIENT_ID,
    state: ctx.cookie.state,
}));

...and in the login page (src/routes/login.page.tsx):

const { data: userData } = useServerSideQuery(async (ctx) => {
    if (code && state === ctx.cookie.state) {
        // ... rest of the code
    }
});

Now if you visit our main page and click "Sign in with GitHub", the whole sign-in routine should still work, but this time with a proper random state token instead of the placeholder.

Remembering the signed-in user

We can use another cookie to store the GitHub access token. The only thing our login page has to do is to get the token and store it in a cookie. Then we can simply redirect to the main page again. Rakkas offers several ways to redirect but, amazingly, some browsers still have problems setting cookies on redirections. So we will use HTML meta refresh for our redirection.

To be able to set a cookie from a page, we export a headers function. So we will have to refactor our code a little. This is how our login.page.tsx gonna look like with this implemented:

import { Head, PageProps, HeadersFunction } from "rakkasjs";

export default function LoginPage({ url }: PageProps) {
    const error = url.searchParams.get("error");

    if (error) {
        return <div>Error: {error}</div>;
    }

    return (
        <div>
            <Head>
                {/* Redirect immediately */}
                <meta httpEquiv="refresh" content="0; url=/" />
            </Head>
            <p>Redirecting...</p>
        </div>
    );
}

export const headers: HeadersFunction = async ({
    url,
    requestContext: ctx,
}) => {
    if (url.searchParams.get("error")) {
        return { status: 403 };
    }

    const code = url.searchParams.get("code");
    const state = url.searchParams.get("state");

    if (code && state === ctx.cookie.state) {
        const { access_token: token } = await fetch(
            "https://github.com/login/oauth/access_token" +
                `?client_id=${process.env.GITHUB_CLIENT_ID}` +
                `&client_secret=${process.env.GITHUB_CLIENT_SECRET}` +
                `&code=${code}`,
            {
                method: "POST",
                headers: { Accept: "application/json" },
            }
        ).then((r) => r.json<{ access_token: string }>());

        if (token) {
            ctx.setCookie("token", token, {
                httpOnly: true,
                secure: import.meta.env.PROD,
                sameSite: "strict",
                maxAge: 60 * 60,
            });

            return {
                // We won't be setting any headers,
                // setCookie will do it for us,
                // so an empty object is fine.
            };
        }
    }

    // Login failed for some reason
    // We'll redirect to set the `error` parameter
    return {
        status: 302,
        headers: {
            Location: new URL(`/login?error=Login%20failed`, url).href,
        },
    };
};

Now when we sign in, we're redirected to the main page and the GitHub access token is stored in a cookie. We can now use the token to fetch the user's profile from GitHub on every request in entry-hattip.ts and make it available in ctx.locals.user. First, let's define our types:

interface GitHubUser {
    // Just the bits we need
    login: string;
    name: string;
    avatar_url: string;
}

declare module "rakkasjs" {
    interface ServerSideLocals {
        postStore: KVNamespace;
        user?: GitHubUser;
    }
}

And then put the user's profile in ctx.locals.user (right after the state cookie handling code):

if (ctx.cookie.token) {
    const user: GitHubUser = await fetch("https://api.github.com/user", {
        headers: {
            Authorization: `token ${ctx.cookie.token}`,
        },
    }).then((r) => r.json());

    ctx.locals.user = user;
}

Finally, we can read this data in our main layout to show the login status:

import { LayoutProps, useServerSideQuery } from "rakkasjs";

export default function MainLayout({ children }: LayoutProps) {
    const {
        data: { clientId, state, user },
    } = useServerSideQuery((ctx) => ({
        clientId: process.env.GITHUB_CLIENT_ID,
        state: ctx.cookie.state,
        user: ctx.locals.user,
    }));

    return (
        <>
            <header>
                <strong>uBlog</strong>
                <span style={{ float: "right" }}>
                    {user ? (
                        <span>
                            <img src={user.avatar_url} width={32} />
                            &nbsp;
                            {user.name}
                        </span>
                    ) : (
                        <a
                            href={
                                "https://github.com/login/oauth/authorize" +
                                `?client_id=${clientId}` +
                                `&state=${state}`
                            }
                        >
                            Sign in with GitGub
                        </a>
                    )}
                </span>
                <hr />
            </header>
            {children}
        </>
    );
}

Yes, yes, ugly. We'll get there. Let's update our create form action handler in index.page.tsx to set the author metadata in the created post. We should also disallow creating posts if the user is not logged in:

export const action: ActionHandler = async (ctx) => {
    if (!ctx.requestContext.locals.user) {
        return { data: { error: "You must be signed in to post." } };
    }

    // Retrieve the form data
    const data = await ctx.requestContext.request.formData();
    const content = data.get("content");

    // Do some validation
    if (!content) {
        return { data: { error: "Content is required" } };
    } else if (typeof content !== "string") {
        // It could be a file upload!
        return { data: { error: "Content must be a string" } };
    } else if (content.length > 280) {
        return {
            data: {
                error: "Content must be less than 280 characters",
                content, // Echo back the content to refill the form
            },
        };
    }

    await ctx.requestContext.locals.postStore.put(generateKey(), content, {
        metadata: {
            // We don't have login/signup yet,
            // so we'll just make up a user name
            author: ctx.requestContext.locals.user.login,
            postedAt: new Date().toISOString(),
        },
    });

    return { data: { error: null } };
};

Cool, we can now tweet under our own user name!

There's no point in showing the create post form if the user is not logged in, since we're not gonna allow it anyway. Let's update our page component to handle that too:

export default function HomePage({ actionData }: PageProps) {
    const {
        data: { posts, user },
    } = useServerSideQuery(async (ctx) => {
        const list = await ctx.locals.postStore.list<{
            author: string;
            postedAt: string;
        }>();

        const posts = await Promise.all(
            list.keys.map((key) =>
                ctx.locals.postStore
                    .get(key.name)
                    .then((data) => ({ key, content: data }))
            )
        );

        return { posts, user: ctx.locals.user };
    });

    return (
        <main>
            <h1>Posts</h1>
            <ul>
                {posts.map((post) => (
                    <li key={post.key.name}>
                        <div>{post.content}</div>
                        <div>
                            <i>{post.key.metadata?.author ?? "Unknown author"}</i>
                            &nbsp;
                            <span>
                                {post.key.metadata?.postedAt
                                    ? new Date(post.key.metadata.postedAt).toLocaleString()
                                    : "Unknown date"}
                            </span>
                        </div>
                        <hr />
                    </li>
                ))}
            </ul>

            {user && (
                <form method="POST">
                    <p>
                        <textarea
                            name="content"
                            rows={4}
                            defaultValue={actionData?.content}
                        />
                    </p>

                    {actionData?.error && <p>{actionData.error}</p>}

                    <button type="submit">Submit</button>
                </form>
            )}
        </main>
    );
}

Sign out

We need one last feature: the ability to sign out. We will add a "sign out" button that will post to a /logout API route which sign the user out by deleting the access token cookie. The button (and the form) will look like this:

<form method="POST" action="/logout">
    <button type="submit">Sign out</button>
</form>

Now we'll add an API route to handler the action. Rakkas API routes are modules named <path>.api.ts (or .js). The export request handling functions which have the same name as the HTTP method they handle, but in lowercase. For example, the POST handler will be named post. DELETE handlers, however, are named del because delete is a reserved word in JavaScript. According to this, we're supposed to name our logout route src/routes/logout.api.ts and it will look simply like this:

import { RequestContext } from "rakkasjs";

export function post(ctx: RequestContext) {
    ctx.deleteCookie("token");
    return new Response(null, {
        status: 302,
        headers: {
            Location: new URL("/", ctx.request.url).href,
        },
    });
}

And now we will be able to sign out!

Deploying

Now that we've added all the features we need, we can deploy our application. We'll test locally with Miniflare first but there is one more thing to take care of: GitHub API requires a user agent for all requests. It was working fine so far, because Rakkas uses node-fetch to make requests and node-fetch automatically sets the user agent. It's not the case for Miniflare or Cloudflare Workers. So we'll have to set it ourselves in entry-hattip.ts:

const user: GitHubUser = await fetch("https://api.github.com/user", {
    headers: {
        Authorization: `token ${ctx.cookie.token}`,
        // Put your own GitHub name here
        "User-Agent": "uBlog by cyco130",
    },
}).then((r) => r.json());

Add the same header to the request in login.page.tsx's headers function. Now we're set:

npm run build # Build the application
npm run local -- --port 5173

We told miniflare to use port 5173, because that's the address we gave GitHub while registering our app. If all goes well, our app should run on Miniflare too!

We're almost ready to deploy. But first, we have to change our GitHub app's callback URL to point at our deployment URL (should be something ending with workers.dev). Actually a better idea is to register a second app and keep the first one for development. Register your app, generate a client key and add a [vars] to your wrangler.toml like this:

[vars]
GITHUB_CLIENT_ID = "<your client ID>"
GITHUB_CLIENT_SECRET = "<your client secret>"

Now we're ready to deploy with npm run deploy! If all goes well, your app will be deployed to Cloudflare Workers and you should be able to sign in with GitHub, create posts with your username, and sign out. You can share it with your friends to test if it works for them too.

Small bugs

If you played around enough with it, you may have noticed a small bug: If the Cloudflare edge that is running your app happens to be on a different time zone than you are, the server will render a different date than the client. The same will happen if your browser's locale is different than the server's. The easiest way to fix this is to always render the date on the client. Rakkas has a ClientOnly component that does exactly that. We'll fix it and redeploy:

<ClientOnly fallback={null}>
    {new Date(post.key.metadata.postedAt).toLocaleString()}
</ClientOnly>

Also, you may occasionally find that sometimes new tweets don't show up in the list unless you refresh your browser a few times. That's because Cloudflare Workers KV is an eventually consistent store. So, occasionally, your changes may not be immediately visible. It may actually take up to a minute to fully synchronize. This is part of the nature of the store we're using and also happens quite rarely so we'll leave it alone for now.

What's next?

In the next article, we'll finish our do some styling and do the finishing touches. Then we'll discuss some ideas to take the project further.

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

Sign in with GitHub

Fatih Aygün — Sat, 13 Aug 2022 08:06:28 +0000

GitHub offers a free API for authenticating users. It's based on OAuth, an open standard for authentication. OAuth is a fairly large subject but our use case is not that complicated. You can learn more on GitHub's documentation but this is how it works in essence:

We'll create a GitHub app and enter a callback URL there. We'll receive a client ID and a client secret (which are just random-looking strings).
We'll add a "Sign in with GitHub" link to our page. The link will point to a GitHub URL that will include our client ID and a random string that we'll generate (called "state") in query parameters.
GitHub will show the user a page depending on their authentication status:
- The user will be shown the GitHub sign-in page (only if they are not already signed in).
- The user will be asked whether they want to authorize our app (only if they have not already authorized our app recently).
- If they accept (or had accepted recently), GitHub will redirect the user to the callback URL we defined in step 1.
The redirection will include a code and the state we sent in step 2 as query parameters. If the state doesn't match the random string that we sent, we'll know something fishy is going on and abort the process. Otherwise, we'll send a POST request to https://github.com/login/oauth/access_token along with our client ID, client secret, and the code we received as a query parameter. If everything goes well, GitHub will reply with an access token.
We'll use the access token in the Authorization header every time we want to get the user's profile data from GitHub.

We have a plan. Let's start.

Create a GitHub app

Head over to GitHub Developer Settings, click OAuth Apps on the left and then click the "New OAuth app" button. It's gonna ask you a few questions. Enter http://localhost:5173 for the homepage URL and http://localhost:5173/login for the callback URL, and fill the rest as you like. We're giving localhost addresses because we have to test our app before deploying to its final URL. You can just update the URLs when you deploy or create a new app and keep this one for testing and development.

After you submit the form, you'll end up on a page where you will see your app's client ID. You will also see a "Generate a new client secret" button. Go ahead and generate one and copy both into a new file in your repository's root directory and save it with the name .env. It should look like this:

GITHUB_CLIENT_ID=<your client ID>
GITHUB_CLIENT_SECRET=<your client secret>

It's good practice to keep our app secrets and configuration in environment variables. Now add this file to your .gitignore file so you don't accidentally push your secret to GitHub. To load this into the environment during development, we'll install the dotenv package:

npm install -D dotenv

Then we'll import it and call it in our vite.config.ts. The file will end up looking like this:

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

dotenv.config();

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

Now we will be able to access the variables with, e.g., process.env.GITHUB_CLIENT_ID in our server-side code. process.env is a Node-specific global but Rakkas makes it available on Cloudflare Workers too.

Adding a "sign in" link

Right now, we only have a single page. But it's not gonna be like that forever. We probably want to see the "sign in" link on the header of every page. Rakkas has a layout system for shared elements like this. Layouts wrap nested layouts and pages under the same directory and its subdirectories. So if we create a layout.tsx file in the src/routes directory, it will wrap every single page on our app.

We said the "sign in" link would point to a GitHub URL. That URL, according to GitHub's documentation, is https://github.com/login/oauth/authorize?client_id=<CLIENT_ID>${clientId}&state=<STATE>. Our client ID is in process.env.GITHUB_CLIENT_ID which is only accessible on the server-side. So we'll use useServerSideQuery again to access it. We'll tackle the handling of the state parameter later, let's give it 12345 for now. So here's the first draft of our src/routes/layout.tsx:

import { LayoutProps, useServerSideQuery } from "rakkasjs";

export default function MainLayout({ children }: LayoutProps) {
    const {
        data: { clientId, state },
    } = useServerSideQuery(() => ({
        clientId: process.env.GITHUB_CLIENT_ID,
        state: "12345",
    }));

    return (
        <>
            <header>
                <strong>uBlog</strong>
                <a
                    style={{ float: "right" }}
                    href={
                        "https://github.com/login/oauth/authorize" +
                        `?client_id=${clientId}` +
                        `&state=${state}`
                    }
                >
                    Sign in with GitGub
                </a>
                <hr />
            </header>
            {children}
        </>
    );
}

When you launch the dev server you'll see that we have a site header now. And the "Sign in with GitHub" link will take you to GitHub's authorization page. If you go ahead and authorize your app GitHub will redirect you to a URL that looks like http://localhost:5173/login?code=<BUNCH_OF_RANDOM_LOOKING_CHARS>&state=12345. http://localhost:5173/login is the URL we entered as the callback URL and the rest are the parameters sent by GitHub. Of course, you will get a 404 error because we haven't implemented that endpoint yet. Let's do that now.

Login callback

We'll create a src/routes/login.page.tsx file to implement the login callback. In it, we will use the code query parameter to get an access token from GitHub and then use that access token to get the user's profile data. We will use the useServerSideQuery hook again because we don't want to expose our client secret to the client. Remember, the useServerSideQuery callback runs on the server and will not be part of the client bundle. Let's see what the profile data looks like first by printing it as JSON:

import { PageProps, useServerSideQuery } from "rakkasjs";

export default function LoginPage({ url }: PageProps) {
    const error = url.searchParams.get("error");
    const code = url.searchParams.get("code");
    const state = url.searchParams.get("state");

    const { data: userData } = useServerSideQuery(async () => {
        if (code && state === "12345") {
            const { access_token: token } = await fetch(
                "https://github.com/login/oauth/access_token" +
                    `?client_id=${process.env.GITHUB_CLIENT_ID}` +
                    `&client_secret=${process.env.GITHUB_CLIENT_SECRET}` +
                    `&code=${code}`,
                {
                    method: "POST",
                    headers: { Accept: "application/json" },
                }
            ).then((r) => r.json<{ access_token: string }>());

            if (token) {
                const userData = fetch("https://api.github.com/user", {
                    headers: {
                        Authorization: `token ${token}`,
                    },
                }).then((r) => r.json());

                return userData;
            }
        }
    });

    if (error) {
        return <div>Error: {error}</div>;
    }

    return <pre>{JSON.stringify(userData, null, 2)}</pre>;
}

If everything goes well, you should see your GitHub user profile data in JSON format when you click on "Sign in with GitHub". Mine looks like this:

{
    "login": "cyco130",
    "id": 10846005,
    "node_id": "MDQ6VXNlcjEwODQ2MDA1",
    "avatar_url": "https://avatars.githubusercontent.com/u/10846005?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/cyco130",
    "html_url": "https://github.com/cyco130",
    "followers_url": "https://api.github.com/users/cyco130/followers",
    "following_url": "https://api.github.com/users/cyco130/following{/other_user}",
    "gists_url": "https://api.github.com/users/cyco130/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/cyco130/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/cyco130/subscriptions",
    "organizations_url": "https://api.github.com/users/cyco130/orgs",
    "repos_url": "https://api.github.com/users/cyco130/repos",
    "events_url": "https://api.github.com/users/cyco130/events{/privacy}",
    "received_events_url": "https://api.github.com/users/cyco130/received_events",
    "type": "User",
    "site_admin": false,
    "name": "Fatih Aygün",
    "company": "Lityum AŞ",
    "blog": "",
    "location": "Istanbul",
    "email": null,
    "hireable": null,
    "bio": "Programmer, musician, amateur linguist.",
    "twitter_username": "cyco130",
    "public_repos": 32,
    "public_gists": 4,
    "followers": 26,
    "following": 25,
    "created_at": "2015-02-04T09:24:28Z",
    "updated_at": "2022-06-29T03:02:45Z"
}

Success! We've accomplished quite a lot! It's a good time to take a break!

What's next?

In the next article, we'll finish our authentication feature. We will use cookies to remember who is who.

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

Create post form

Fatih Aygün — Wed, 10 Aug 2022 18:46:39 +0000

In the two previous articles, we set up and deployed a project that can retrieve data from Cloudflare Workers KV store. Now we're gonna create a form for creating new posts.

Rakkas has built-in support for form handling. We'll start with creating the form itself by adding the following lines to src/routes/index.page.tsx, right after the closing </ul> tag of the post list and before the closing </main> tag:

<form method="POST">
    <p>
        <textarea name="content" rows={4} />
    </p>
    <button type="submit">Submit</button>
</form>

Fairly conventional so far. The cool part is the action handler. If you export a function named action from a page file, Rakkas will call it when a form is submitted to that address. The code in the action function will always run on the server-side, similar to the code in the useServerSideQuery callback. Let's add it to the bottom of the file:

// ActionHandler type is defined in the `rakkasjs` package.
// Add it to your imports.
export const action: ActionHandler = async (ctx) => {
    // Retrieve the form data
    const data = await ctx.requestContext.request.formData();
    const content = data.get("content");

    // Do some validation
    if (!content) {
        return { data: { error: "Content is required" } };
    } else if (typeof content !== "string") {
        // It could be a file upload!
        return { data: { error: "Content must be a string" } };
    } else if (content.length > 280) {
        return { data: { error: "Content must be less than 280 characters" } };
    }

    await ctx.requestContext.locals.postStore.put(generateKey(), content, {
        metadata: {
            // We don't have login/signup yet,
            // so we'll just make up a user name
            author: "Arden Eberhardt",
            postedAt: new Date().toISOString(),
        },
    });

    return { data: { error: null } };
};

function generateKey() {
    // This generates a random string as the post key
    // but we'll talk more about this later.
    return Math.random().toString(36).slice(2);
}

If you spin up the dev server, you will see that you can add new posts now!

Improving the user experience

Cool, but we have several UX problems here. First of all, we're not showing validation errors to the user.

If the action handler returns an object with the data key, that data will be available to the page component in the actionData prop. It will be undefined if there were no form submissions. So we'll change the signature of the HomePage component like this:

// PageProps type is defined in the `rakkasjs` package.
// Add it to your imports.
export default function HomePage({ actionData }: PageProps) {
    // ...

Now we'll add an error message right above the submit button:

<form method="POST">
    <p>
        <textarea name="content" rows={4} />
    </p>

    {actionData?.error && <p>{actionData.error}</p>}

    <button type="submit">Submit</button>
</form>

Now you'll be able to see an error message if you try to submit an empty post or if the content's too long. But it's still not very user-friendly that the form is cleared when there is an error. One solution is to echo back the form data in the return value of the action handler and then use it to populate the form. So we'll change the part that returns the "too long" error like this:

-   return { data: { error: "Content must be less than 280 characters" } };

+   return {
+       data: {
+           error: "Content must be less than 280 characters",
+           content, // Echo back the form data
+       },
+   };

And then we'll use it to initialize our textarea element's default value:

<textarea name="content" rows={4} defaultValue={actionData?.content} />

If you try again and submit a post that is too long, you will see that the form will not be cleared and you will be able to edit the content down to 280 characters to re-submit.

Sorting the posts

You may have noticed that newly created posts are inserted at a random position in the list. It would be better if we saw them in the newest-first order. The KV store doesn't have a method for sorting by content or metadata. But it always returns the items in the alphabetical order of the keys. Instead of random keys, we could use the creation time but it would be the exact opposite of what we want since 2022-08-01T00:00:00.000Z comes after 2020-08-01T00:00:00.000Z when sorted alphabetically.

So we'll have to get creative here. The JavaScript Date instances have a getTime() method that returns a timestamp which is the number of milliseconds since January 1, 1970. You can also create a Date from a timestamp with, e.g. new Date(0). What's the date for the timestamp 9,999,999,999,999? new Date(9_999_999_999_999) returns November 20, 2286. I'm fairly certain ublog will not be around for that long. So my idea is to use 9_999_999_999_999 - new Date().getTime() as our key.

To make sure that the keys are small we'll use the base-36 encoding and to ensure alphabetical sorting, we'll left-pad the result with zeroes. The base-36 encoding of 9,999,999,999,999 is 3jlxpt2pr which is 9 characters long. So we will left-pad until the key is at least 9 characters:

function generateKey() {
    return (9_999_999_999_999 - new Date().getTime())
        .toString(36)
        .padStart(9, "0");
}

The keys should be unique but what if two users create posts at the same time? We can reduce the possibility of key collisions to "practically zero" by appending a random string at the end:

function generateKey() {
    return (
        (9_999_999_999_999 - new Date().getTime()).toString(36).padStart(9, "0") +
        Math.random().toString(36).slice(2).padStart(6, "0")
    );
}

In a real application, you'd probably want to use a more sophisticated key generation routine like UUID v4 but this is fine for our purposes.

Now if you spin up the dev server, you will see that the posts are sorted by creation time except for the mock ones. You can fix those by changing their made-up keys from 1-3 to z1-z3 so that they always stay at the bottom.

That's it! We can now add new posts to the list and view them in the newest-first order.

Testing with Miniflare

Since anyone can create posts now, it's best if we don't deploy this to Cloudflare Workers yet. But we can test our workers bundle with Miniflare by building with npm run build and launching with npm run local. Miniflare has built-in KV store support so everything should work as expected.

What's next?

In the next article, we'll implement authentication (sign-in/sign-up) using the GitHub OAuth API.

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

KV store

Fatih Aygün — Wed, 10 Aug 2022 14:58:00 +0000

In the previous article, we set up our project and deployed a "Hello World" app to Cloudflare Workers. Now we're gonna look at storing and retrieving our data in Cloudflare Workers KV store. It's a simple but useful key-value store and it has a generous free tier that we can use for our project. We'll start by installing a few dependencies:

npm install -D @cloudflare/workers-types @miniflare/kv @miniflare/storage-memory

@cloudflare/workers-types provides global type definitions for the KV API. We'll add it to our tsconfig.json file in compilerOptions.types:

{
    "compilerOptions": {
        // ... existing compiler options ...
-       "types": ["vite/client"]
+       "types": ["vite/client", "@cloudflare/workers-types"]
    }
}

The KV API is only available on Cloudflare Workers. But, during development, Rakkas runs our app on Node.js. Fortunately, the Miniflare project has a KV implementation for Node. The other two packages that we've installed (@miniflare/kv and @miniflare/storage-memory) are what we need to be able to use the KV API during development. Let's create a src/kv-mock.ts file and create a local KV store to store our ublog posts ("twits") while testing:

import { KVNamespace } from "@miniflare/kv";
import { MemoryStorage } from "@miniflare/storage-memory";

export const postStore = new KVNamespace(new MemoryStorage());

const MOCK_POSTS = [
    {
        key: "1",
        content: "Hello, world!",
        author: "Jane Doe",
        postedAt: "2022-08-10T14:34:00.000Z",
    },
    {
        key: "2",
        content: "Hello ublog!",
        author: "Cody Reimer",
        postedAt: "2022-08-10T13:27:00.000Z",
    },
    {
        key: "3",
        content: "Wow, this is pretty cool!",
        author: "Zoey Washington",
        postedAt: "2022-08-10T12:00:00.000Z",
    },
];

// We'll add some mock posts
// Rakkas supports top level await
await Promise.all(
    // We'll do this in parallel with Promise.all,
    // just to be cool.
    MOCK_POSTS.map((post) =>
        postStore.put(post.key, post.content, {
            metadata: {
                author: post.author,
                postedAt: post.postedAt,
            },
        })
    )
);

As you can see we also added some mock data because our application doesn't have a "create post" feature yet. This way, we can start fetching and showing some posts before we implement it.

The put method of the store accepts a key, a value, and some optional metadata. We'll use the content to store the actual post content, and the metadata to store the author and the date the post was created. The key has to be unique but other than that it is currently meaningless, we'll get to that later.

Now we should make this store available to our application's server-side code. The best place to do it is the HatTip entry which is the main server-side entry point of a Rakkas application. It's an optional file which is not part of the generated boilerplate so we'll add it manually as src/entry-hattip.ts:

import { createRequestHandler } from "rakkasjs";

declare module "rakkasjs" {
    interface ServerSideLocals {
        postStore: KVNamespace;
    }
}

export default createRequestHandler({
    middleware: {
        beforePages: [
            async (ctx) => {
                if (import.meta.env.DEV) {
                    const { postStore } = await import("./kv-mock");
                    ctx.locals.postStore = postStore;
                } else {
                    ctx.locals.postStore = (ctx.platform as any).env.KV_POSTS;
                }
            },
        ],
    },
});

Woah, that's a lot of unfamiliar stuff. Let's break it down.

The HatTip entry is supposed to default export a HatTip request handler. So we create one with createRequestHandler. createRequestHandler accepts a bunch of options to customize the server's behavior. One of them is middleware which is used to inject middleware functions into Rakkas's request handling pipeline. HatTip middlewares are similar to Express middlewares in many ways. So the concept should be familiar if you've used Express before.

We add our middleware before Rakkas processes our application's pages (beforePages). It's, in fact, the earliest interception point. In the middleware, we inject our store into the request context object which will be available to our application's server-side code. The request context object has a locals property dedicated to storing application-specific stuff like this.

The bit starting with declare module "rakkasjs" is a TypeScript technique for extending interfaces declared in other modules. In this case, we're extending the ServerSideLocals interface which is the type of ctx.locals where ctx is the request context object.

import.meta.env.DEV is a Vite feature. Its value is true during development and false in production. Here, we use it to determine whether we should create a mock KV store or use the real one on Cloudflare Workers.

For production, HatTip's Cloudflare Workers adapter makes the so-called bindings available in ctx.platform.env. ctx.platform's type is unknown because it changes depending on the environment. So we use as any to appease the TypeScript compiler. KV_POSTS is just a name we've chosen for the binding name of our posts store.

Thanks to this fairly simple middleware, the KV store that will hold our posts will be available to our application as ctx.locals.postStore where ctx is the request context.

Fetching data from the KV store

Now we'll spin up a dev server with npm run dev and edit the src/pages/index.page.tsx file to fetch and display our mock posts. Rakkas has a very cool data fetching hook called useServerSideQuery. With this hook, you can put your server-side code right inside your components without having to create API endpoints:

import { useServerSideQuery } from "rakkasjs";

export default function HomePage() {
    const { data: posts } = useServerSideQuery(async (ctx) => {
        // This callback always runs on the server.
        // So we have access to the request context!

        // Get a list of the keys and metadata
        const list = await ctx.locals.postStore.list<{
            author: string;
            postedAt: string;
        }>();

        // Get individual posts and move things around
        // a little to make it easier to render
        const posts = await Promise.all(
            list.keys.map((key) =>
                ctx.locals.postStore
                    .get(key.name)
                    .then((data) => ({ key, content: data }))
            )
        );

        return posts;
    });

    return (
        <main>
            <h1>Posts</h1>
            <ul>
                {posts.map((post) => (
                    <li key={post.key.name}>
                        <div>{post.content}</div>
                        <div>
                            {/* post.key.metadata may not be available while testing for */}
                            {/* reasons we'll cover later. That's why we need the nullish */}
                            {/* checks here */}
                            <i>{post.key.metadata?.author ?? "Unknown author"}</i>
                            &nbsp;
                            <span>
                                {post.key.metadata
                                    ? new Date(post.key.metadata.postedAt).toLocaleString()
                                    : "Unknown date"}
                            </span>
                        </div>
                        <hr />
                    </li>
                ))}
            </ul>
        </main>
    );
}

That's it! Now you should see a list of mock posts if you visit http://localhost:5173. Don't worry about the ugly looks yet. We'll cover styling later.

Building for production

Now build your application for production and deploy it:

npm run build
npm run deploy

Unfortunately, if you visit your production URL now, you will get an error. That's because we haven't created a KV store on Cloudflare Workers yet. We'll do that with the wrangler CLI::

npx wrangler kv:namespace create KV_POSTS

If everything goes well, you should see a message like this:

Add the following to your configuration file in your kv_namespaces array:
{ binding = "KV_POSTS", id = "<YOUR_KV_NAMESPACE_ID>" }

We will do just that and we will add the following at the end of our wrangler.toml file:

[[kv_namespaces]]
binding = "KV_POSTS"
id = "<YOUR_KV_NAMESPACE_ID>"

Then we will deploy again with npm run deploy. This time the error is gone but we'll still not see any posts. Let's add a few with wrangler CLI:

npx wrangler kv:key put --binding KV_POSTS 1 "Hello world!"
npx wrangler kv:key put --binding KV_POSTS 2 "Ooh! Pretty nice!"
npx wrangler kv:key put --binding KV_POSTS 3 "Wrangler lets us add new values to KV!"

Unfortunately, wrangler CLI doesn't allow us to add metadata to our posts so we'll see "Unknown author" and "Unknown date" in the UI but other than that... IT WORKS, YAY! We have a working data store for our app!

You can also visit the Cloudflare Dashboard and go to Workers > KV to add/remove/edit your values in your store. If you do, you will notice that Cloudflare uses the same KV store mechanism to store your static assets.

Cleaning up

If you're going to put your code in a public repo, you should not expose your KV store ID. Just make a copy of your wrangler.toml as wrangler.example.toml and redact the KV store ID from the copy. Then add wrangler.toml to your .gitignore and run git rm wrangler.toml --cached before committing. I'm not entirely sure whether this is required but there has been a data breach in the past involving the KV store ID so it's best to play safe.

What's next?

In the next article, we'll add a form to allow users to add new posts.

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

Project setup

Fatih Aygün — Wed, 10 Aug 2022 08:23:00 +0000

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.

Rakkas 0.6: Bleeding-edge React framework

Fatih Aygün — Mon, 08 Aug 2022 16:19:00 +0000

💃 Rakkas, the bleeding edge React framework powered by Vite, has just released version 0.6.0. First release since December, this is the largest and least backward compatible update so far. But we believe the quantity and the quality of the new features justify the number of breaking changes. See if you agree.

React 18

Rakkas 0.6 was redesigned from the ground up to be compatible with React 18. It supports the new Concurrent Mode, Streaming SSR, and Suspense for data fetching.

Streaming SSR means that Rakkas apps, when doing server-side rendering (SSR), now send chunks of a page's HTML as soon as they are available instead of waiting until everything is fully rendered. This way, the user starts seeing meaningful content as soon as possible instead of waiting in front of a blank screen. Streaming SSR integrates seamlessly with Suspense and the new data fetching system we'll describe below.

If you're worried about streaming SSR interfering with SEO, you'll be relieved to know that Rakkas also implements dynamic rendering: It sends fully rendered pages with correct status codes, HTTP headers, and head tags to search bots while streaming HTML to normal browsers. In any case, you can opt out of streaming on a global, per-route, or per-request basis without giving up Suspense-based data fetching.

New data fetching system

Instead of the page-centric data fetching functions that ran before the page was rendered (“fetch-then-render”), Rakkas 0.6 adopts a Suspense-based data fetching system (“render-as-you-fetch“). The new system comes in the form of useQuery and useMutation hooks that implement a Suspense-only subset of the react-query API.

API-less data fetching

If you're familiar with Next.js, you know how cool getServerSideProps is. With it, you can put, say, your database access code right next to your page component without worrying about implementing and maintaining a REST/GraphQL/RPC/whatever API. Next.js cleverly strips this function and its imports from the client bundle. During SSR, it's called directly. On the client, Next sends a request to the server instead of calling the function.

We believe we've one-upped the ease of use of this data fetching method. Enter useServerSideQuery:

import db from "./my-db-access-lib";

export default function UserCard(props) {
    const userName = props.userName;

    const userQuery = useServerSideQuery(() => {
        if (typeof userName !== "string") {
            // This is server-side code,
            // always validate user input!
            throw new Error("Invalid request");
        }

        return db.user.findOne(userName);
    });

    return (
        <div class="card">
            <img src={userQuery.data.image} />
            <caption>{userQuery.data.fullName}</caption>
        </div>
    );
}

This isn't a page, just an ordinary React component that you can use on many pages. In Rakkas 0.6 pages aren't very special in terms of data fetching anymore. Just like getServerSideProps, the function passed to useServerSideQuery (useSSQ for short) always runs on the server: On the client, a request is sent to the server instead of calling the function directly. Rakkas performs a code transform similar to Next's to strip the function and its imports from the client bundle.

useSSQ's return type is inferred, so, if you're using TypeScript, you get IDE completion just like you would with a local function call. Another nice feature is that, unlike other similar data fetching hooks, useSSQ doesn't return loading or error states. Those are handled higher up in the component tree, with Suspense fallbacks and error boundaries respectively. This way, your component code stays clean and focused.

One practical application of useSSQ that may not be immediately obvious is circumventing CORS restrictions when calling third-party APIs:

const result = useServerSideQuery(() =>
    fetch("https://some.cors.restricted.api.example.com").then((res) =>
        res.json(),
    ),
);

This works because the fetch call inside useServerSideQuery runs on the server-side (Rakkas makes fetch globally available on all deployment targets) and, as such, is not affected by CORS restrictions. In effect, it creates an ad-hoc CORS proxy.

Paired with Remix-inspired action handlers or useServerSideMutation, useSSQ lets you write code as if the server-client barrier didn't exist. But, of course, API routes are still available to allow you to implement REST, GraphQL, RPC etc. endpoints that you can access via useQuery and useMutation or other methods if you prefer to stick with traditional data fetching.

Avoiding waterfalls

Even though we said that in Rakkas 0.6 pages and layouts are not very special in terms of data fetching anymore, you can still have a preload function to start fetching early. preload functions of a page and its parent layouts all run in parallel to avoid late discovery of data dependencies and waterfalls. preload also provides a way to inject SEO-critical title and meta tags into the page even when streaming.

Other new features

Rakkas 0.6 is now built on HatTip, an HTTP server library that abstracts away the differences between various JavaScript runtimes building on the web standards like Request, Response, and streams. Rakkas already ran on Node, Vercel Serverless Functions, Netlify Functions, and Cloudflare Workers. HatTip integration adds support for Vercel Edge, and Netlify Edge. There's also preliminary support for Deno (including Deno Deploy). Bun support is work in progress.

HatTip also makes it possible to integrate with Express or other Connect-compatible Node.js server frameworks: Now you can use Express middleware and routes in your Rakkas app or build your app as an Express middleware to be used in other Express apps.

The new route guards feature allows you to do things like making some routes available to logged-in users only. Catch-all routes and better 404 handling are also among the new features.

Conclusion

If this is the first time you hear of Rakkas, it has other cool features like a lightning-fast development server (courtesy of Vite), file system routing, nested layouts, static site generation, and more.

Rakkas uses experimental and/or beta features of React and Vite. As such, expect breaking changes until we hit 1.0. But go ahead and give it a try and share your thoughts. Star us on Github, join our Discord server, and follow me on Twitter for updates.

If you have any questions, problems, or suggestions open a Github issue. If you want to contribute, fork and send a pull request. Check out the open issues to see how you can help. As always, all feedback is welcome.

Brief History of Frontend Web Technologies

Fatih Aygün — Thu, 10 Feb 2022 06:51:29 +0000

In the beginning there was HTML. But it was dull and lifeless until the <blink> tag came along and made it come alive. Then came JavaScript to meet our increasingly sophisticated text blinking needs. A year later CSS arrived to separate the concerns of document structure and text blinking in an elegant way. It helped us survive the browser wars relatively unscathed.

In 2006, Sass (and a little later Less and Stylus) appeared to make text blinking less painful. But the real highlight of the year was the grandiose entrance of jQuery, which was, until quite recently, the way to make text blink through DOM manipulation. The defiant $ function was the Spartacus which led JavaScript to a successful revolution that would end up enslaving their former master HTML.

Then began the dark age of IE6 compatibility. IE6 made consistent cross-browser text blinking unnecessarily complicated. All the other browsers had nicer blinking features, but people kept using the damn thing until big names abandoned it and took a firm stand ("we want blink!") to put the final nail in its coffin in 2010.

2010 was also the year AngularJS came along to make us question the ways of the one true JS library, the Holy jQuery. The mighty $ was challenged by ng-, but stood its ground and still survives today.

Three years later, in 2013, came <React /> along with its JSX syntax. By this time you needed JavaScript programs to compile your JavaScript programs into JavaScript programs... to make nicer and better performing blinking texts. Some thought of JSX as a counter-revolution by HTML loyalists, and some as the final blow to HTML's hegemony over JavaScript. Whichever is true, it did save the web: This was also the year that Firefox decided to kill the mighty <blink> tag! If it wasn't for React, the PascalCase offspring of the long forgotten originator of all things web would not exist: the shiny new <Blink> component!¹

Did I forget what? Come on, need I mention the F word? To its credit, it was the best way to make images blink for quite a long while though!

¹ The implementation thereof is left as an exercise for the reader.

Three Cool Rakkas Features that Next.js Lacks

Fatih Aygün — Mon, 20 Dec 2021 13:02:13 +0000

💃 Rakkas, the lightning fast Next.js alternative powered by Vite, has just released version 0.5.0 (check out my previous post for an introduction). Although it replicates or offers alternatives for most Next.js features (like file-system router, server-side rendering, data fetching, and static site generation), Next.js still has many features that Rakkas doesn't support yet. This new release closes the gap, if by a little, by providing much improved SSR support (thanks to Vite 2.7), implementing rendering modes (static, server-side, or client-side) and support for deploying on serverless environments. But it's not all about playing catch-up: Rakkas does offer a few cool features of its own that Next.js lacks.

1. Deploy on Cloudflare Workers

The new Rakkas release brings first-class support for deploying on Vercel serverless functions, Netlify functions, and Cloudflare Workers. Vercel, the makers of Next.js, is of course the go-to option for Next.js apps. Netlify is also a popular deployment target. But Cloudflare Workers is an entirely different beast: It is a lighter-weight and cheaper solution compared to container-based serverless functions offerings. But the environment is much more similar to service workers in browsers than to Node. Next.js, being closely tied to Node, doesn't support Cloudflare Workers as of yet. Following Svelte Kit's lead, Rakkas was designed with this use case in mind from the get-go.

Note that we're not talking about Cloudflare Pages, which Next.js supports as a static deployment target, but actual server-rendered (well, technically speaking “edge-rendered”) React applications with support for API routes. This is a rare feature among React frameworks (I'm only aware of Flareact and Vitedge).

Check out the updated Rakkas RealWorld Demo to see how the same full-stack application is deployed on Vercel, Netlify, Cloudflare Workers, and Node; all connected to the same Postgres database hosted on Supabase. In serverless versions, authentication requests are proxied to the Node server because CPU time limit may be too low to allow secure password hashing. They also use the Prisma data proxy for accessing the database while the Node server uses Prisma directly.

2. Localize your URLs

This new Rakkas feature allows you to have localized URLs: Say you have a website with a “Home” page (/en), an “About us” page (/en/about-us) and a “Products” page (/en/products). In a multilingual site, you'd probably want your French language URLs to be something like /fr, /fr/qui-sommes-nous and /fr/produits. Don't get hung up on the exact URL structure, you have complete control: You can omit the prefixes in English pages, put different versions on a different subdomain (fr.example.com) or domain (example.fr), or opt out of URL translation (/fr/about-us) for instance. All you need to provide is a function that parses the language from the URL and translates the localized URL into a default form that Rakkas will use to determine what to render.

If you need an international landing pages (say / redirects to /en or /fr based on the visitor's language preference), Rakkas also offers optional Accept-Language and navigator.languages based language detection and redirection that can be overridden by a cookie. It even works on static sites where JavaScript redirection is used. Rakkas will render a list of links to the localized URLs when JavaScript is disabled.

Next.js does have a feature to detect the language from the URL but the URLs cannot be rewritten: You will have /fr/about and /fr/products (or example.fr/about etc.) which is, frankly, of limited use.

3. Nest your layouts

Not many websites consist of completely independent pages. Most sites have shared elements like a header, a footer, and a navigation menu that are common to many pages. Rakkas provides a nested layout system to handle this use case and more. You can have a layout.jsx (or tsx) and all pages in the same directory and pages or nested layouts in its subdirectories will be wrapped in your layout component.

Next.js has a similar feature but Rakkas layouts can nest arbitrarily by following the same filesystem-based organization as pages, they can have their own blocking data fetchers for static/server-side rendering, and they can provide shared data for lower level layouts and pages via the layout context feature. They can also abort the rendering of the current page by returning an error or redirecting to another page, useful for implementing login protected pages for instance.

Pages don't even need to share a common URL path prefix to share a layout: You can put pages that should share a layout under a directory with a name that starts with an underscore (_). For example you could have a directory structure like this:

pages/
- layout.jsx (the main layout, common to all pages)
- _app/ (layout group for most pages)
- layout.jsx (common layout for most pages)
- page.jsx (path: /)
- about.page.jsx (path: /about)
- blog.page.jsx (path: /blog)
- _admin/ (layout group for admin pages)
- layout.jsx (common layout for admin pages)
- settings.page.jsx (path: /settings)
- users.page.jsx (path: /users)

Final thoughts

We all know Next.js is awesome. But Rakkas does put a few unique features on the table. It's still young and not yet ready for production use but go ahead and give it a try and share your thoughts. Star us on Github and talk about Rakkas if you like what you see. If you have any questions, problems, or suggestions open a Github issue. If you want to contribute, fork and send a pull request. Check out the open issues to see how you can help. All feedback is welcome, positive or negative.

How to get client-side navigation right

Fatih Aygün — Mon, 13 Dec 2021 20:50:51 +0000

How many times have you ctrl-clicked (or cmd-clicked) on a link to open it in a new tab but it opened in the current tab or didn't open at all? How many times have you clicked on a link in a long document and when you clicked back it took you to the top of the document instead of where you had left? Client-side navigation bugs are so widespread that it's hard to believe the technique is almost 20 years old! So I decided to write down all the issues I've ever encountered and build a library that tries to solve them once and for all.

Normally, when you click on a link, your browser loads a new page from the URL specified in the href attribute of your link (an a or area element). Client-side navigation refers to the practice of using JavaScript to control page transitions without a full reload, which usually results in a snappier user experience. Despite its popularity, many implementations are broken or lacking: history manipulation, scroll restoration, ctrl + click / cmd + click / right click behavior, loading state handling etc. are often buggy or non-existent. In many cases this actually makes the user experience worse than classic navigation by breaking user expectations.

Having appeared in early 2000s, the practice has ushered in the era of Single Page Applications (SPAs). Earliest attempts used the #hash part of the URL and the window.onhashchange event. Since it is normally used for scrolling to a specific section of a document, a hash-only navigation doesn't cause a full page reload. Developers took advantage of this to implement client-side navigation with history (back/forward buttons) support. In early 2010s, the history API support landed in popular browsers which allowed using real URL paths instead of hashes.

Despite a whole decade that has passed since the arrival of the history API, there are still a myriad of challenges to be solved when implementing client-side navigation.

Intercepting history changes

window.onpopstate event is fired when the user clicks on the back/forward buttons or one of the back, forward or go methods of the history API is called. location and history.state (which is a place you can store extra data about the current location) are updated before the onpopstate event is fired.

Unfortunately this event is not fired when history.pushState or history.replaceState is called. This means that a client-side library solution must provide its own navigation function, because, barring horrible hacks, it has no way to be notified when the user of the library calls these methods.

It's not fired when the user clicks on a link either. This means that we have to listen to the click events to prevent the default behavior and handle the navigation ourselves.

Dedicated `Link` component vs global click handler

Preventing the browser's default behavior when the user clicks on a link can be achieved in two ways: 1) by providing a dedicated Link component that renders an a element with an attached an onclick handler, or 2) by attaching a global onclick handler to the body element.

The first approach has the advantage of being explicit: There are no surprises. Next.js and React Router both follow this approach. Opting out of client-side navigation is trivial: Just use a plain a element.

The second approach is implicit but it is easier to use in most cases: Sometimes you don't control the HTML contents of a page. Maybe it was rendered from Markdown residing in a database or a CMS. It may be hard or impossible to control the rendered a elements in such cases. SvelteKit uses this second approach. Opting out of client-side navigation is still possible: We can interpret, for instance, the presence of a rel="external" attribute as a signal for letting the browser handle the navigation. The downside of the second approach is that one has to be careful about event handling order. If you attach an onclick handler to the a element, it will run after the global one which may not be what you want. You have to use { capture: true } if you want to alter the click behavior of a link.

A third, hybrid approach is also possible: We can implement a LinkContainer component that captures the onclick events of the a elements that it contains. It solves the “pre-rendered HTML that we don't control” problem while remaining fairly explicit.

Whichever approach we choose, a Link component is still useful for styling active (or pending) links differently, a nice feature to have in navigation menus for instance.

Knowing when not to interfere

When listening to onclick events, it is important to know when to leave the handling to the browser. The following cases should be considered:

Was preventDefault() called before our handler?
Does the a element have a href attribute at all?
Was it a left click? Right click and middle click usually have other functions.
Were any of the modifier keys pressed? Ctrl, shift, alt, meta, command etc. keys are used to trigger alternative functions like opening in a new tab or window.
Does the a element have a target attribute whose value is not _self?
Does the a element have a download attribute?

If any of these conditions is met, we should let the browser handle the event.

Pending navigation

Very simple apps can render a new page synchronously but transitioning from one page to another usually has to be asynchronous in real-world use cases. Modern bundlers support code splitting and pages are natural code splitting boundaries. Loading the code for the next page is an asynchronous operation. Also, you usually need to fetch some data before rendering a page. This is also an asynchronous operation.

During classic navigation, most browsers keep showing the old page along with some kind of loading state indicator until the new one loads. This is much more useful than showing a blank loading page. Ideally, a client-side navigation solution should replicate this behavior.

The requirement of supporting asynchronous navigation causes a very subtle complication: Inevitably there will be a moment where location.href does not match currently rendered page contents. This may cause mismatches in links with relative URLs: Say you are on page /foo and you initiate a client-side navigation to /foo/bar. If there is a link whose href is baz (a relative link), it will be pointing to /foo/baz instead of /baz while the navigation is underway. One way to solve this problem is to have a base element in the document head whose href property is always kept in sync with the currently rendered location.

Scroll restoration

Classic navigation has support for scroll restoration: When the user navigates back or forward, the browser will restore the scroll position. This behavior has to be simulated when using client-side navigation.

Modern browsers have support for history.scrollRestoration which can be set to manual or auto. The former is the default value and means that the browser will not restore the scroll position. You might think that you can set it to auto and be done with it. Unfortunately, this is not the case if you have to support asynchronous rendering like we discussed above. The scroll position needs to be restored after the new page has been rendered in its entirety. Consider this scenario: You're at the bottom of a page that has contents that don't fit in the viewport (/long). You navigate to a page that does fit (/short). When you click back, automatic scroll restoration will try to scroll to the original position but unless you are able to render /long synchronously, it will fail because the contents of /short will be showing while /long is still loading and they fit the page so there's nowhere to scroll to.

This problem severely reduces the usefulness of history.scrollRestoration. A decent client-side navigation solution must set it to manual and handle scroll restoration manually, after the new page has been fully rendered. One way to approach this is to assign a unique ID to each location, keeping track of it in history.state and use it as a sessionStorage key to store the scroll position.

One more point to remember when implementing scroll restoration is to be careful about not breaking the normal behavior of #hash links.

Blocking navigation

Classic navigation has limited support for navigation blocking in the form of onbeforeunload event. When set up correctly, it will show a confirmation dialog before navigating away from the current page. This is useful to remind the user that they might lose unsaved data.

When using client-side navigation, we can show a custom dialog box in some cases. This requires “canceling” the navigation when the user decides to stay on the page. The challenge here is that, when the user clicks the back or forward button, location.href is already updated by the time the onpopstate event is called. This means that we don't know if we should go back or forward to cancel the navigation. To solve this, we can use history.state to keep track of the current location's history index and compare it to the last rendered index in order to compute a delta value to pass to history.go for “taking back” the navigation attempt. Then we can show a dialog box to ask the user if they really want to leave the page. If the answer is no, we stop, if the answer is yes, we redo the navigation using history.go(-delta).

We still need an onbeforeunload fallback in case the user clicks on a hard link or simply closes the tab.

Knave

Having failed in finding a simple library that provides all of these features, I've created knave, a framework-agnostic client-side navigation library in order to address all of these challenges once and for all. The knave-react package contains its React bindings. PRs that implement bindings for other frameworks are welcome.

Rakkas: Next.js alternative powered by Vite

Fatih Aygün — Thu, 14 Oct 2021 11:04:41 +0000

Rakkas, the lightning fast Next.js alternative powered by Vite, has just released version 0.4.0.

If you're not familiar with Vite, it's an instance of a new class of tools, sometimes called non-bundlers, that leverage modern browsers' native EcmaScript modules support to do away with the bundling during development. This results in instant server start and much faster updates than traditional bundlers like Webpack, Rollup, or Parcel. These new tools (another example is Snowpack) improve developer experience so much that, once you try, you will never want to go back to your old tooling.

Vite (and therefore Rakkas) supports TypeScript, JSX, hot module replacement with React fast refresh, CSS modules, PostCSS, CSS preprocessors (just install sass, less, or stylus), and handling of static assets out of the box.

Rakkas is a MIT-licensed React framework similar to Next.js, it's not a clone. In fact, if you're familiar with Svelte -a user interface framework (like React or Vue)- many of Rakkas's features are inspired by SvelteKit, Svelte's web application building tool.

Important features of Rakkas are:

⚡ Lightning fast development server
📁 Intuitive file system-based routing
🖥️ Hassle free server-side rendering
📄 Static site generation (NEW!)
☸️ SPA-style client-side navigation
⬇️ Simple but effective data fetching system
⚙️ API routes to build and organize your backend
📚 Extensive documentation

The file system router maps your source files to web pages. For example, if you want a page /about, you just default-export a React component from src/pages/about.page.jsx or src/pages/about/page.jsx. Route parameters are also encoded in the file name: src/pages/users/[userName].page.jsx is rendered for /users/jane, /users/joe, and so forth. In this case, your component receives a params prop and the user name is available as params.userName.

Rakkas supports nested layouts for elements common to more than one page, like headers, footers, navigation bars etc. Each page or layout can fetch its own data using an isomorphic fetch function. For advanced use cases, you can implement your own data fetching helper functions or classes. The implementation can be different for the server and the client, opening up the possibility of avoiding the network roundtrip and serialization/deserialization while doing SSR.

API routes have a file system router similar to pages: /src/api/users.endpoint.js implements the endpoint /api/users. Functions exported from this file handle similarly named HTTP methods (i.e. get for GET, post for POST etc.) by taking a request object and returning a response object. You can also define middlewares for impementing abstractions relating to more than one endpoint.

If you're reading this on a Chromium-based desktop browser, you can try Rakkas online on StackBlitz. For a full-on experience, Rakkas project generator create-rakkas-app comes with lots of features, all optional: TypeScript, ESLint, StyleLint, Prettier, Cypress, and jest (for unit testing and/or API testing). It supports yarn and pnpm in addition to npm. To get started, just create a new project directory and run npx create-rakkas-app@latest, then follow the prompt. The optional demo app demonstrates a toy fullstack todo app that communicates via a simple REST API.

If you want to go further, there are integration examples with other popular tools:

There is also a RealWorld port (Rakkas implementation of the RealWorld specification), a simple but complete fullstack application demonstrating how to approach building a REST API, accessing your database (via Prisma), handling authentication, testing, and more.

Rakkas is still young and is not ready for production yet. But go ahead and give it a try and share your thoughts. Star us on Github and talk about Rakkas if you like what you see. If you have any questions, problems, or suggestions open a Github issue. If you want to contribute, fork and send a pull request. All feedback is welcome, positive or negative.

Rakkas can now power fullstack RealWorld

Fatih Aygün — Sun, 22 Aug 2021 20:47:10 +0000

Rakkas “the dancing web framework” is a web framework built on React and Vite. RealWorld is a demo app specification with more than 100 implementations in various frontend and backend frameworks. The just released version 0.3.0 of Rakkas now has a feature set rich enough to power a fullstack implementation of RealWorld which works even with JavaScript disabled (a good test of Rakkas's SSR abilities). See it in action!

This port served as a test bed while developing the new version of Rakkas: We fixed the bugs we stumbled upon, we added features we missed, and we redesigned APIs we deemed unergonomic.

It also served as a test bed for establishing Rakkas best practices: Session management, authentication, unit testing, API testing, end-to-end testing, data validation, database access, and many other things that need to be done in a real world application has been tackled. See the github repo for a more in depth explanation of how everything works.

The new version also comes with much expanded documentation and the next version will focus on static site generation.

Although still in early development and not ready for production use, we feel that this release puts Rakkas on the map as an increasingly promising contender for building real-world web applications. So go ahead and give it a try: you can even do it in your browser!

DEV Community: Fatih Aygün

Styling with UnoCSS

Conclusion

Using cookies

Remembering the signed-in user

Sign out

Deploying

Small bugs

What's next?

Sign in with GitHub

Create a GitHub app

Adding a "sign in" link

Login callback

What's next?

Create post form

Improving the user experience

Sorting the posts

Testing with Miniflare

What's next?

KV store

Fetching data from the KV store

Building for production

Cleaning up

What's next?

Project setup

Project setup

Customization

Setting up for Cloudflare Workers

Deploying

What's next?

Rakkas 0.6: Bleeding-edge React framework

React 18

New data fetching system

API-less data fetching

Avoiding waterfalls

Other new features

Conclusion

Brief History of Frontend Web Technologies

Three Cool Rakkas Features that Next.js Lacks

1. Deploy on Cloudflare Workers

2. Localize your URLs

3. Nest your layouts

Final thoughts

How to get client-side navigation right

Intercepting history changes

Dedicated Link component vs global click handler

Knowing when not to interfere

Pending navigation

Scroll restoration

Blocking navigation

Knave

Rakkas: Next.js alternative powered by Vite

Rakkas can now power fullstack RealWorld

Dedicated `Link` component vs global click handler