Forem: ishan

Authenticating Users in Astro & React Apps with Better Auth

ishan — Tue, 02 Dec 2025 12:40:13 +0000

This post was originally published in my website here.

Authentication is a critical foundation for every contemporary web application, but establishing it is often one of the most significant, time-intensive hurdles developers encounter. The solution? Introducing Better Auth API: a framework-independent authentication service designed to revolutionize user management implementation. This detailed tutorial will guide you through creating a fully functional, full-stack application, showcasing the efficiency and ease of Better Auth, powered by Astro for optimal performance.

Why Better Auth?

Traditional auth solutions often require extensive boilerplate code and complex configuration. Better Auth offers:

Zero boilerplate setup
Type-safe APIs with full TypeScript support
Multiple provider support (email/password, OAuth, passkeys)
Framework-agnostic design that works with Astro, React, and beyond

Better Auth automatically handles Astro's unique server-client boundary, providing authentication that works across both environments. Better Auth provides a unified API that adapts to your stack—whether you're using React, Vue, Svelte, or vanilla JavaScript on the frontend, and Node.js, Bun, Deno or any framekworks on javascript ecosystem on the backend.

Setting up Astro

Astro's hybrid architecture (server and client components) works seamlessly with Better Auth. Better Auth requires a database to persist user and session data and leverages Server-Side Rendering (SSR) to manage sessions via cookies.

🛠️ Prerequisites

A new Astro project (e.g., initialized with pnpm create astro@latest).
A database (e.g., PostgreSQL or MongoDB) configured and ready.
An SSR adapter for Astro (e.g., Cloudflare, Vercel, Netlify, or Node) added to your project.

pnpm create astro@latest

Create a Neon (Serverless Postgres) app

If you do not have one already, create a Neon (Serverless Postgres) project.

Save your connection details including your password. Here is the steps involved:

Navigate to the Projects page in the (Neon Console)[https://neon.com/].
Click New Project.
Specify your project settings and click Create Project.
Create a .env file in the root directory of your Astro project, and define a DATABASE_URL key with the connection string obtained as the value.

Adding dependencies

pnpm i better-auth pg @types/pg @astrojs/cloudflare @astrojs/react @tailwindcss/vite react tailwindcss wrangler

better-auth — Authentication toolkit providing server/client auth APIs for modern web apps.
pg — PostgreSQL client for Node.js used to connect and query Postgres databases.
@types/pg — TypeScript type definitions for the pg (PostgreSQL) library.
@astrojs/cloudflare — Astro adapter for deploying your Astro app to Cloudflare Workers.
@astrojs/react — Enables using React components inside an Astro project.
@tailwindcss/vite — Integrates Tailwind CSS directly into Astro/Vite for fast builds and hot reload.
react — UI library for building interactive components inside Astro.
tailwindcss — Utility-first CSS framework used for styling your Astro + React project.
wrangler — Cloudflare’s CLI tool for building and deploying Workers and Worker-based apps.

Adding environment variables

BETTER_AUTH_SECRET="a-32-character-secret"
DATABASE_URL="your database connection string"

You can generate a secret with the code snippet below

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Astro gives you access to Vite’s built-in environment variables support and includes some default environment variables for your project that allow you to access configuration values for your current project.

Adding better-auth

Better Auth comes with first class support for Astro.

We will be creating two utility files, src/auth.ts and src/auth-client.ts to access Better Auth on the server side and client side, respectively.

In the src/auth-client.ts (code below), we are instantiating a new better-auth instance to be used in the client side interactions.

//src/auth-client.ts
import { createAuthClient } from "better-auth/react"
export const { useSession, authClient } = createAuthClient()

In src/auth.ts (code below), you are going to use a Pool to connect to your Postgres instance to persist the sessions and user object in the database, and enable email and password authentication. Astro uses Vite’s built-in support for environment variables, which are statically replaced at build time, and lets you use any of its methods to work with them.

We use import.meta.env.DATABASE_URL to access environment variables inside Astro.

//src/auth.ts
import pkg from 'pg'
import { betterAuth } from 'better-auth'

const { Pool } = pkg

export const auth = betterAuth({
  emailAndPassword: { enabled: true },
  database: new Pool({ connectionString: import.meta.env.DATABASE_URL })
})

Generating schema and API routes

To create the schema per our configuration defined in src/auth.ts file in your database automatically, execute the command below:

npx @better-auth/cli migrate

Let's define an API route to allow you to authenticate users.

Better Auth does the heavy lifting of creating and managing the logic of validating credentials, creating (or updating) the user and relevant session objects in the database. You just need to create a catch-all api route in your Astro project as follows in the src/pages/api/auth/[...all].ts file:

import { auth } from '@/auth'
import type { APIRoute } from 'astro'

export const ALL: APIRoute = async (ctx) => {
  return auth.handler(ctx.request)
}

Intercept all incoming requests using Astro middleware

To make sure that each request maintains a user and session information is accessible over the server-side endpoints, and in .astro pages during server-side rendering, you are going create a middleware that uses Better Auth to decode/encode a user session from the cookie.

Create a file middleware.ts in the src directory with the following code:

import { auth } from '@/auth'
import { defineMiddleware } from 'astro:middleware'

export const onRequest = defineMiddleware(async (context, next) => {
  const isAuthed = await auth.api.getSession({
    headers: context.request.headers,
  })
  if (isAuthed) {
    context.locals.user = isAuthed.user
    context.locals.session = isAuthed.session
  } else {
    context.locals.user = null
    context.locals.session = null
  }
  return next()
})

This will make sure to mark both user and session as null by default, and assign the respective values obtained from the database using the relevant cookies from the request. This allows you to always know the correct state of user authentication.

Creating Index Page

---
import "@/styles/global.css";
import DashboardPage from "@/components/Dashboard";
import Layout from "@/layouts/Layout.astro";

if (!Astro.locals.user?.id) return Astro.redirect("/signin");
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
  </head>
  <body class="container mx-auto p-4">
    <Layout>
      <DashboardPage client:load />
      <Layout />
    </Layout>
  </body>
</html>

This Redirects user to the sign in page if the user is not authenticated.
Shows the information stored in the user object pertaining to the authenticated user.

Let's create a react component for our dashboard page.

import { useEffect } from "react";
import { authClient, useSession } from "@/auth-client";
import "@/styles/global.css";

export default function DashboardPage() {
    const {
        data: session,
        isPending, 
        error, 
        refetch 
    } = useSession()

  useEffect(() => {
    // If not logged in → redirect to signin
    if (!isPending && !session?.user?.id) {
      window.location.href='/'
    }
  }, [session, isPending]);

  const handleSignOut = async (): Promise<void> => {
    await authClient.signOut();
      window.location.href = '/signin'
  };

  if (isPending) {
    return <p>Loading...</p>;
  }

  if (!session?.user) {
    return null; 
  }

  return (
    <div className="container mx-auto py-4">
      <h1 className="font-bold text-xl">
        Hello {session.user.name ?? "User"}
      </h1>

      <h2 className="text-green-500 font-bold text-3xl">
        You&apos;ve authenticated successfully!
      </h2>

      <pre className="mt-4 bg-gray-100 p-4 rounded text-sm">
        {JSON.stringify(session.user, null, 2)}
      </pre>

      <button
        onClick={handleSignOut}
        className="mt-4 px-4 py-2 bg-red-600 text-white rounded"
      >
        Sign Out
      </button>
    </div>
  );
}

Creating Signup

We created a signup page inside the src/pages and imported a React component and used a client:load directive so its hydrated in client. This helps to load and hydrate the component JavaScript immediately on page load.

---
import SignupForm from '@/components/SignupForm' 
import Layout from '@/layouts/Layout.astro'
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
  </head>
  <body>
    <Layout>
      <SignupForm client:load/>
    <Layout />
  </body>
</html>

Also we will make a signup form component which will be a simple form to create a user inside of our Neon database.

import React, { useState } from "react";
import type { FormEvent } from "react";
import { authClient } from "@/auth-client";

export default function SignupPage(): React.JSX.Element {
  const [isLoading, setIsLoading] = useState<boolean>(false);
  const [error, setError] = useState<string>("");

  const handleSubmit = async (e: FormEvent<HTMLFormElement>): Promise<void> => {
    e.preventDefault();
    setIsLoading(true);
    setError("");

    const formData = new FormData(e.currentTarget);

    const name = (formData.get("name") as string) ?? "";
    const email = (formData.get("email") as string) ?? "";
    const password = (formData.get("password") as string) ?? "";

    const response = await authClient.signUp.email({
      name,
      email,
      password,
    });

    if (!response.error) {
      window.location.href = '/'
    } else {
      setError(response.error.message ?? "Signup failed");
    }

    setIsLoading(false);
  };

  return (
    <div className="min-h-screen flex flex-col items-center justify-center p-4">
      <h1 className="font-bold text-3xl py-8">
        Sign up
      </h1>
      <form
        onSubmit={handleSubmit}
        className="flex flex-col gap-3 w-full max-w-sm"
      >
        <input
          required
          type="text"
          name="name"
          placeholder="Name"
          className="border p-2 rounded"
        />

        <input
          required
          type="email"
          name="email"
          placeholder="Email"
          className="border p-2 rounded"
        />

        <input
          required
          type="password"
          name="password"
          placeholder="Password"
          className="border p-2 rounded"
        />

        <button
          type="submit"
          disabled={isLoading}
          className="p-2 bg-blue-600 text-white rounded"
        >
          {isLoading ? "Signing up..." : "Sign up"}
        </button>

        {error && <p className="text-red-500 text-sm">{error}</p>}
      </form>

      <p className="mt-4">
        Already have an account?{" "}
        <a href="/signin" className="underline">
          Sign in
        </a>
      </p>
    </div>
  );
}

Creating Signin

Let's also create a signin page so that we can verify user exists in our DB.

In the frontmatter we check if user is available we redirect to main route.

---
import Layout from "@/layouts/Layout.astro"
import SigninForm from "@/components/SigninForm"

if (Astro.locals.user?.id) return Astro.redirect('/')
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
  </head>
  <body>
    <Layout>
      <SigninForm client:load/>
    <Layout />
  </body>
</html>

Same like before we will create a form submission so that we can login the user and redirect to our desired route.

import type { FormEvent } from "react";
import { useState } from "react";
import { authClient } from "@/auth-client";

export default function SigninPage() {
  const [isLoading, setIsLoading] = useState<boolean>(false);
  const [error, setError] = useState<string>("");

  const handleSubmit = async (e: FormEvent<HTMLFormElement>): Promise<void> => {
    e.preventDefault();
    setIsLoading(true);
    setError("");

    const formData = new FormData(e.currentTarget);

    const email = (formData.get("email") as string) ?? "";
    const password = (formData.get("password") as string) ?? "";

    const response = await authClient.signIn.email({
      email,
      password,
    });

    if (!response.error) {
      window.location.href = '/';
    } else {
      setError(response.error.message ?? "Sign-in failed");
    }

    setIsLoading(false);
  };

  return (
    <div className="min-h-screen flex flex-col items-center justify-center p-4">
      <h1 className="font-bold text-3xl py-8">
        Sign in
      </h1>
      <form
        onSubmit={handleSubmit}
        className="flex flex-col gap-3 w-full max-w-sm"
      >
        <input
          required
          type="email"
          name="email"
          placeholder="Email"
          className="border p-2 rounded"
        />

        <input
          required
          type="password"
          name="password"
          placeholder="Password"
          className="border p-2 rounded"
        />

        <button
          type="submit"
          disabled={isLoading}
          className="p-2 bg-blue-600 text-white rounded"
        >
          {isLoading ? "Signing in..." : "Sign In"}
        </button>

        {error && <p className="text-red-500 text-sm">{error}</p>}
      </form>

      <p className="mt-4">
        Don&apos;t have an account?{" "}
        <a href="/signup" className="underline">
          Sign up
        </a>
      </p>
    </div>
  );
}

We enabled user authentication via credentials method with the help of Better Auth in an Astro application. You have also gained some experience with using middleware in Astro, and understanding how it can help you build dynamic user interfaces.

Conclusion

Whether we're building a content-focused Astro site or a dynamic React application, Better Auth provides the secure, modern authentication solution you need without the typical complexity.

Better Auth's greatest strength might be its developer experience. With automatic API route generation in Astro and React hooks that provide immediate user state, you can implement complete auth flows in minutes rather than days.

Have a question, feedback or simply wish to contact me privately? Shoot me a DM and I'll do my best to get back to you.

You can find the complete source code in Github Link here.

Thank you!

Integrate Cloudflare Turnstile into Astro and React Application

ishan — Fri, 28 Nov 2025 05:09:19 +0000

This post was originally published in my website here.

Form submission interfaces are a critical vector for engagement in any modern web application. Yet, they simultaneously represent a persistent challenge: mitigating the deluge of spam and automated submissions without degrading the UX.

While initial defense layers—such as schema validation, custom server-side validators, and rigorous input sanitization—are fundamental, an additional, robust layer of bot defense is essential.

This guide details the strategic implementation of Cloudflare Turnstile, the privacy-preserving successor to traditional CAPTCHA, integrated within a type-safe Astro and React environment using server-side validation.

🛡️ Cloudflare Turnstile: Redefining Human Verification

Cloudflare Turnstile represents a pivotal shift away from the intrusive visual puzzles of conventional CAPTCHA systems. It is engineered as a privacy-first, non-interactive validation service designed to seamlessly distinguish between legitimate human users and malicious bots.

Instead of demanding user interaction (like solving a puzzle or clicking a checkbox), Turnstile leverages a dynamic suite of non-interactive, in-browser challenges. These challenges rapidly analyze the visitor's environment and behavior patterns.

🛠️ Project Initialization and Key Management

We initiate our project using the latest Astro CLI, providing a robust environment for static and dynamic rendering:

pnpm create astro@latest

Securing Cloudflare Credentials

To enable verification, we must provision the necessary credentials from the Cloudflare Turnstile dashboard.

First, you need to get your site keys from Cloudflare.

Go to the Cloudflare Turnstile dashboard.
Click "Add Site".
Fill in your Site Name and Domain (e.g., localhost for development and your production domain).
Choose the Widget Mode. "Managed" is recommended for the best user experience.
Click "Create".

You will now see your Site Key and Secret Key.

Site Key: Public, and safe to include in your client-side code.

Secret Key: Private. Must never be exposed to the frontend. We'll use this on our server.

Environment Configuration

We must secure the private key using environment variables. Create a .env file at the root of your project:

TURNSTILE_SITE_KEY=your_turnstile_site_key_here
TURNSTILE_SECRET_KEY=your_turnstile_secret_key_here

Crucially, you must add .env to your .gitignore file to prevent committing your secret key to version control.

Now, we need to create an API endpoint in Astro to receive the form submission and validate the Turnstile token.

const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';

export async function verifyTurnstileToken(token: string, secretKey: string): Promise<{
  success: boolean;
  error?: string;
}> {
  try {
    if (!secretKey) {
      console.error('TURNSTILE_SECRET_KEY is not configured');
      return {
        success: false,
        error: 'Server configuration error.',
      };
    }

    const response = await fetch(TURNSTILE_VERIFY_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        secret: secretKey,
        response: token,
      }),
    });

    if (!response.ok) {
      return {
        success: false,
        error: 'Turnstile service unavailable',
      };
    }

    const result = await response.json();

    if (!result.success) {
      console.error('Turnstile verification failed:', result.error_codes);
      return {
        success: false,
        error: 'Verification failed. Please try again.',
      };
    }

    return {
      success: true,
    };
  } catch (error) {
    console.error('Turnstile verification error:', error);
    return {
      success: false,
      error: 'Failed to verify token',
    };
  }
}

We created a function which receives two parameters of token and secret key.

This functioin will verify that the token we pass to turnstile widget is valid.

Creating an API with schema validation

We now construct the Astro API endpoint, which handles the entire submission lifecycle: data retrieval, schema validation (using Valibot), and Turnstile verification.

import { getSecret } from 'astro:env/server';
import { validateContactForm, verifyTurnstileToken } from '@/utils/index';
import type { ContactFormData, FormState } from '@/types/contact';
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const TURNSTILE_SECRET_KEY = getSecret('TURNSTILE_SECRET_KEY');

  try {
    const formData = await request.formData();

    const data = {
      name: formData.get('name'),
      email: formData.get('email'),
      message: formData.get('message'),
      'cf-turnstile-response': formData.get('cf-turnstile-response'),
    };

    const validationResult = validateContactForm(data);
    if (!validationResult.success) {
      return new Response(
        JSON.stringify({
          success: false,
          error: validationResult.error,
        } as FormState),
        { status: 400, headers: { 'Content-Type': 'application/json' } }
      );
    }

    const validatedData = validationResult.data!;

    const turnstileResult = await verifyTurnstileToken(
      validatedData['cf-turnstile-response'],
      TURNSTILE_SECRET_KEY as string
    );

    if (!turnstileResult.success) {
      return new Response(
        JSON.stringify({
          success: false,
          error: turnstileResult.error || 'Turnstile verification failed',
        } as FormState),
        { status: 400, headers: { 'Content-Type': 'application/json' } }
      );
    }

    await handleContactFormSubmission(validatedData);

    return new Response(
      JSON.stringify({
        success: true,
        message: 'Thank you for your message! We will get back to you soon.',
      } as FormState),
      { status: 200, headers: { 'Content-Type': 'application/json' } }
    );
  } catch (error) {
    console.error('Form submission error:', error);
    return new Response(
      JSON.stringify({
        success: false,
        error: 'An error occurred. Please try again later.',
      } as FormState),
      { status: 500, headers: { 'Content-Type': 'application/json' } }
    );
  }
};

async function handleContactFormSubmission(data: ContactFormData): Promise<void> {
  console.log('Form submission data:', {
    name: data.name,
    email: data.email,
    message: data.message,
    timestamp: new Date().toISOString(),
  });
}

Creating client component

The front-end is managed by a React component, rendered client-side in Astro using the client:load directive. We use the useActionState hook to manage the form's asynchronous submission state.

---
export const prerender = false

import ContactForm from '@/components/Contactform';
import Layout from '@/layouts/Layout.astro';

---

<Layout>
  <div class="min-h-screen flex items-center justify-center px-4">
    <div class="w-full max-w-xl bg-white shadow-md rounded-2xl p-8">
      <h1 class="text-3xl font-semibold mb-6 text-gray-800">Contact Us</h1>
      <ContactForm client:load />
    </div>
  </div>
</Layout>

So, inside of our component we will load turnstile widget and use it along side with other form fields.

import { useRef, useEffect, useActionState } from "react";
import type { FormState } from "@/types/contact";
import { submitAction } from "@/actions/contact";

export default function ContactForm() {
  const formRef = useRef<HTMLFormElement>(null);

  const [formState, formAction, isPending] = useActionState<FormState>(
    submitAction as any,
    { message: "" }
  );

  // Load Turnstile script
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js";
    script.async = true;
    document.head.appendChild(script);

    return () => {
      const s = document.querySelector(
        'script[src="https://challenges.cloudflare.com/turnstile/v0/api.js"]'
      );
      if (s) document.head.removeChild(s);
    };
  }, []);

  return (
    <form
      ref={formRef}
      action={formAction}
      className="flex flex-col gap-4"
    >

      {/* All form fields goes here */}

      {/* Turnstile */}
      <div
        className="cf-turnstile w-full"
        data-sitekey="0x4AAAAAACDAp2pSvhjq3_Wm"
        data-size="flexible"
      />

      {/* Error */}
      {formState?.error && (
        <div className="p-3 bg-red-100 text-red-800 rounded-md">
          {formState.error}
        </div>
      )}

      {/* Success */}
      {formState?.success && (
        <div className="p-3 bg-green-100 text-green-800 rounded-md">
          {formState.message}
        </div>
      )}

      <button
        type="submit"
        disabled={isPending}
        className={`p-3 px-6 bg-blue-600 text-white rounded-md text-base font-semibold 
          hover:bg-blue-700 transition 
          ${isPending ? "opacity-60 cursor-not-allowed" : ""}`}
      >
        {isPending ? "Submitting…" : "Submit"}
      </button>
    </form>
  );
}

In the code above we used a modern hook available to us useActionState. This helps us to maintain the state of form like loading, submitted and current state. Its really handy to deal with forms with this new hook.

Conclusion

And that's it! You've successfully fortified your Astro and React form against bots using Cloudflare Turnstile. This setup provides a robust security layer without compromising user experience. Say goodbye to confusing CAPTCHAs and hello to a cleaner, safer form.

Have a question, feedback or simply wish to contact me privately? Shoot me a DM and I'll do my best to get back to you.

You can find the complete source code in Github Link here.

Thank you!

Hono and Cloudflare Workers: Building Your Edge API in Minutes!

ishan — Sun, 01 Jun 2025 10:06:26 +0000

Looking to build blazing-fast, globally distributed APIs? In this guide, we'll take a look into how to deploy our first Hono-powered "Hello World" API on Cloudflare in just minutes! Super-fast API at the edge with Hono and Cloudflare combo.

Hono provides a lightweight, high-performance runtime for building web APIs and edge apps, while Cloudflare’s edge network ensures that these apps are deployed globally with ultra-low latency, DDoS protection, and scalability.

🔥 Why this combination?

Hono: It's a "tiny, blazing fast, and production-ready web framework." Designed for the edge, it offers familiar API patterns (like Express.js) but with incredible performance.

Cloudflare Workers: These are serverless functions that run on Cloudflare's edge network, closest to our users. This means incredibly low latency and high scalability, without managing any infrastructure.

Together, they're a match made in heaven for building efficient, global APIs. Let's start making a file for our hello world server.

// src/index.ts (main worker file)

import { Hono } from 'hono';
const app = new Hono();
app.get('/', (c) => {
  return c.text('Hello Hono with Cloudflare Worker API!'); // plain text response
});
export default app;

🎩 Unpacking the Magic

Let's break down what's happening in our concise TypeScript code, line by line, to see how we're crafting this edge-powered "Hello World."

import { Hono } from 'hono';:

This is our first step! We're bringing in the core Hono object from the Hono library. Think of Hono as our minimalist yet mighty toolkit for building web APIs. It provides all the necessary functions to handle requests and send responses.

const app = new Hono();:

Here, we're initializing our Hono application. The app constant now holds our entire web application instance. It's like setting up a miniature server ready to listen for incoming requests. All our routes and logic will be attached to this app object.

app.get('/', (c) => { ... });:

This is where the action happens! We're defining a specific "route" for our API.

app.get('/')

means we're telling our app to listen for GET requests that come to the very root path (/) of our application.

> (c) => { ... }

is the "handler function" that gets executed whenever a request matches this route. The c (short for "Context") is a powerful object that Hono provides. It's our gateway to everything about the current request – headers, query parameters, environment variables, and crucially, methods to send back a response.

return c.text('Hello Hono with Cloudflare Worker API!');:

Inside our handler function, this line is the heart of our "Hello World." We're using the c.text() method from the Context object to send a simple, plain text response back to the client. The message "Hello Hono!" is what anyone accessing our API endpoint will see. It's concise, direct, and perfect for a quick demonstration.

export default app;:

Finally, this line is critical for Cloudflare Workers. It tells the Cloudflare Worker environment that our app object is the primary export and should be used to handle all incoming HTTP requests. Without this, Cloudflare wouldn't know how to run our application!

🚀 Getting It Live

Deploying this is incredibly straightforward using Cloudflare's wrangler CLI tool. It’s the official tool for deploying and managing Cloudflare Workers.

You can easily install it with pnpm by running:

pnpm install -g wrangler

After installing wrangler and logging into our Cloudflare account, we'd typically just save this code as src/index.ts (or index.ts in a wrangler project) and deploy with command below.

wrangler deploy

In moments, our "Hello Hono with Cloudflare Worker API!" API will be live on Cloudflare's global network!

🎯 Conclusion

This is just the tip of the iceberg. With Hono and Cloudflare Workers, we can build powerful APIs, render dynamic content, handle forms, and much more, all with the benefits of edge computing.

Optimistic UI with Remix: The Game-Changer You Need to Implement Now

ishan — Sun, 01 Jun 2025 09:19:50 +0000

Optimistic UI or commonly also known as ‘Pending UI’ has been around for ages. We can create an optimistic UI in any framework or any language. Libraries like TanStack Query and SWR provide the framework for developers to implement optimistic updates when working with the React ecosystem.

But, Remix makes it a lot easier to implement an optimistic UI than most other frameworks out there in the wild.

Optimistic UI is a powerful pattern that makes your web applications feel incredibly fast and responsive. Instead of waiting for a server confirmation, the UI updates immediately after a user action, assuming the action will succeed. If the server does confirm success, great! If it fails, the UI gracefully reverts to its previous state, often with an error message.

Unlike traditional client-heavy frameworks, Remix embraces native browser features such as forms, requests, and responses, enabling developers to ship faster, more resilient applications. Many React-based frameworks rely on useState for managing pending UI during network interactions, Remix simplifies this with useNavigation and useFetcher.

⏳ Types of Fallback UI's

We can separate out Optimistic update, Pending UI or Optimistic UI into three main logical categories.

Skeleton fallbacks: Displays a visual placeholder outlining the structure of upcoming content. It's typically used when loading non-critical data for initial page rendering.
Busy indicators: Shows a visual sign while an action is being processed by the server. It's used when the outcome is uncertain, requiring a wait for the server's response before updating the UI.
Optimistic UI: Updates the UI with an expected state before receiving the server's response. It's used when the outcome can be reliably predicted, enabling immediate feedback.

These are the cases where we make a mutation to our data and wait for the server to provide us a response that the mutation has succeeded. Adding predictability behaviour inside our application for a better resilient and sleek user experience.

In this post, we'll dive into implementing Optimistic UI in a Remix.run application, combined with Mock Service Worker(MSW) for robust API mocking and intercepting API requests into our application. Essential for development and testing. It allows us to intercept network requests and define mock responses right in the browser, simulating API behavior without needing a real backend running. This is invaluable for rapid development and testing edge cases like API failures.

💪 Project Setup and File structure

npx create-remix@latest my-fruits-app 
cd my-fruits-app

We will stick with a simple barebones file structure for our application. Which might look something like this.

my-optimistic-fruits-app/
├── app/
│   ├── routes/
│   │   └── _index.tsx  (Our main component for displaying fruits)
│   ├── entry.client.tsx (To start MSW in dev mode)
│   └── utils/
│       └── api.ts       (Our API helper functions)
├── src/
│   └── mocks/
│       ├── handlers.ts  (MSW request handlers)
│       └── browser.ts   (MSW setup for browser)
└── package.json

🎁 Installing MSW

MSW isn't just a testing tool; it's a game-changer for developer experience (DX). By intercepting network requests at the service worker level, MSW allows you to:

Develop without a Backend: Mock complex API scenarios (like network delays, specific success payloads, or various error states) right in your browser, even if your backend isn't ready or accessible.
Isolate Frontend Logic: Focus purely on your UI and data flow, knowing exactly how your API will respond, without worrying about flaky network connections or third-party service downtimes.
Build Robust UIs: Precisely simulate edge cases like API failures, allowing you to thoroughly test the resilience and error-handling of your optimistic updates.

pnpm add msw --save-dev

Let’s start by installing the preferred library where we will define handlers and intercept the HTTP requests for getting our fruits from our fruits API.

// src/mocks/handlers.ts
import { http, HttpResponse } from 'msw';


export const handlers = [
 http.get('/api/fruits', () => {
   // Adding MSW interceptor and simulate a slight network delay
   return HttpResponse.json(
     [
       { id: '1', name: 'Apple', color: 'red' },
       { id: '2', name: 'Banana', color: 'yellow' },
       { id: '3', name: 'Orange', color: 'orange' },
     ],
     { status: 200, statusText: 'OK' },
     { delay: 500 } // 500ms
   );
 }),


 http.post('/api/fruits', async ({ request }) => {
   console.log('MSW: Intercepted POST /api/fruits');
   const data = await request.json();
   const newFruitName = data.name;


   // Simulate a random server error
   if (Math.random() < 0.2) {
     console.log('MSW: Simulating a server error for new fruit');
     return HttpResponse.json(
       { error: 'MSW simulated server error: Failed to add fruit!' },
       { status: 500 },
       { delay: 800 }  // 800ms
     );
   }


   // Simulate successful creation
   const newFruit = { id: `msw-${Date.now()}`, name: newFruitName, color: 'green' };
   return HttpResponse.json(
     newFruit,
     { status: 201 },
     { delay: 800 } // 800ms
   );
 }),
];

Let’s import the export function into our main file that will intercept requests in the browser.

// src/mocks/browser.ts
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';


export const worker = setupWorker(...handlers);

⚡️ Integrate MSW into Remix Client Entry

We need to tell Remix to start the MSW worker when our client-side application boots up, but only in development.

// app/entry.client.tsx
import { RemixBrowser } from '@remix-run/react';
import { startTransition, StrictMode } from 'react';
import { hydrateRoot } from 'react-dom/client';


async function hydrate() {
 // Only start MSW in development environment
 if (process.env.NODE_ENV === 'development') {
   const { worker } = await import('~/mocks/browser');
   await worker.start({ onUnhandledRequest: 'bypass' }); // Start the worker and bypass unhandled requests
   console.log('🌈 MSW worker started for awesome fruit mocking!');
 }


 startTransition(() => {
   hydrateRoot(
     document,
     <StrictMode>
       <RemixBrowser />
     </StrictMode>
   );
 });
}


if (window.requestIdleCallback) {
 window.requestIdleCallback(hydrate);
} else {
 setTimeout(hydrate, 1);
}

✅ Creating API helper function

Instead of directly calling a database, our Remix loader and action will now make standard fetch requests to /api/fruits.

MSW will intercept these during development 💣 !

// app/utils/api.ts

export type Fruit = {
   id: string;
   name: string;
   color: string;
};


export async function fetchFruits(): Promise<Fruit[]> {
   const response = await fetch('/api/fruits'); //  MSW Interceptors
   if (!response.ok) {
       const errorData = await response.json().catch(() => ({})); // Try to parse error
       throw new Error(errorData.error || 'Failed to fetch fruits');
   }
   return response.json();
}


export async function createFruit(name: string): Promise<Fruit> {
   const response = await fetch('/api/fruits', { // MSW Interceptors
       method: 'POST',
       headers: {
           'Content-Type': 'application/json',
       },
       body: JSON.stringify({ name }),
   });


   const data = await response.json();
   if (!response.ok) {
       throw new Error(data.error || 'Failed to create fruit');
   }
   return data;
}

🎯 Adding Optimistic UI into our Remix Route

Now for the core of our application: _index.tsx. This file will handle loading the fruits, displaying them, and the form for adding new ones with optimistic updates.

We will add necessary import we need for our main index file. Which looks like this

// app/routes/_index.tsx


import type { ActionFunctionArgs, LoaderFunctionArgs } from "@remix-run/node";
import { json } from "@remix-run/node";
import { useLoaderData, useFetcher } from "@remix-run/react";
import { useState, useEffect } from "react";
import { fetchFruits, createFruit, Fruit } from "~/utils/api";

After this we can add our server function which will run on the server and re-runs after mutation is done. Loader functions in Remix that load data for your routes before rendering the UI. They're mostly used to fetch data that your component needs on initial load inside an SSR app.

// app/routes/_index.tsx
export async function loader({ request }: LoaderFunctionArgs) {
 try {
   const fruits = await fetchFruits();
   return json({ fruits });
 } catch (error: any) {
   console.error("Loader error:", error);
   return json({ fruits: [], error: error.message || "Failed to load fruits" }, { status: 500 });
 }
}

Also, action functions in Remix that handle form submissions or other POST/PUT/DELETE requests. They manage server-side logic and then return data or redirection instructions.

// app/routes/_index.tsx
export async function action({ request }: ActionFunctionArgs) {
 const formData = await request.formData();
 const name = formData.get("name");


 if (typeof name !== "string" || name.trim() === "") {
   return json({ error: "Fruit name is required!" }, { status: 400 });
 }


 try {
   const newFruit = await createFruit(name.trim());
   return json({ newFruit });
 } catch (error: any) {
   return json({ error: error.message || "Failed to add fruit." }, { status: 500 });
 }
}

// Component
export default function Index() {
 const { fruits: serverFruits, error: loaderError } = useLoaderData<typeof loader>();
 const fetcher = useFetcher<typeof action>();


 // State to hold our optimistically added fruit
 const [optimisticFruit, setOptimisticFruit] = useState<Fruit | null>(null);


 // Combine server fruits with the optimistic fruit for display
 const displayFruits = [
   // If the fetcher is submitting AND we have an optimistic fruit, prepend it
   ...(fetcher.state === 'submitting' && optimisticFruit
     ? [{ ...optimisticFruit, id: `optimistic-${optimisticFruit.id}` }]
     : []),
   ...serverFruits, // The actual fruits from the server
 ];


 // Handler for form submission
 const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
   const form = event.currentTarget;
   const formData = new FormData(form);
   const name = formData.get("name");


   if (typeof name === "string" && name.trim() !== "") {
     // 1. Optimistic Update
     setOptimisticFruit({
       id: Date.now().toString(),
       name: name.trim(),
       color: 'gray',
     });


     // 2. Submit the form to the Remix action using fetcher
     // The `action` prop here points to the route's action, or a specific API path
     fetcher.submit(formData, { method: "post", action: "/api/fruits" });


     // Clear the input field for a smooth user experience
     form.reset();
   }
   event.preventDefault(); // Prevent default browser form submission
 };


 useEffect(() => {
   if (fetcher.data) {
     if (fetcher.data.error) {
       // If the server reported an error, revert the optimistic change
       setOptimisticFruit(null);
       alert(`Failed to add fruit: ${fetcher.data.error}`); 
// Simple error feedback
     } else if (fetcher.data.newFruit) {
       // If successful, clear the optimistic state.
       // Remix's revalidation will cause the loader to run again,
       // fetching the *actual* updated list of fruits from MSW
       // which will now include the newly added fruit.
       setOptimisticFruit(null);
     }
   }
 }, [fetcher.data]);


 return (
   <div>
     <h1>🍓🥕 My Optimistic Fruit List 🍏🍋</h1>


     <fetcher.Form onSubmit={handleSubmit} style={{ marginBottom: '20px' }}>
       <input
         type="text"
         name="name"
         placeholder="Enter new fruit name"
         required
         disabled={fetcher.state === 'submitting'} // Disable input while submitting
       />
       <button
         type="submit"
         disabled={fetcher.state === 'submitting'} // Disable button while submitting
         style={{ padding: '8px 15px', borderRadius: '4px', border: 'none', background: '#007bff', color: 'white', cursor: 'pointer' }}
       >
         {fetcher.state === 'submitting' ? 'Adding Fruit...' : 'Add Fruit'}
       </button>
     </fetcher.Form>


     {/* Display errors from action or loader */}
     {(fetcher.data && fetcher.data.error) && (
       <p style={{ color: "red" }}>Error: {fetcher.data.error}</p>
     )}
     {loaderError && <p style={{ color: "red", marginTop: '10px' }}>Loader Error: {loaderError}</p>}




     <h2>🍽️ Available Fruits</h2>
     <ul style={{ listStyle: 'none', padding: 0 }}>
       {displayFruits.map((fruit) => (
         <li
           key={fruit.id} // Should be Unique
           style={{
             opacity: fruit.id.startsWith('optimistic-') ? 0.6 : 1,
             fontStyle: fruit.id.startsWith('optimistic-') ? 'italic' : 'normal',
             color: fruit.id.startsWith('optimistic-') ? '#888' : '#333'
           }}
         >
           {fruit.name}
           {fruit.id.startsWith('optimistic-') && fetcher.state === 'submitting' && (
             <span> (Pending...)</span>
           )}
         </li>
       ))}
       {displayFruits.length === 0 && !loaderError && !fetcher.state === 'submitting' && (
         <p>No fruits yet. Add some!</p>
       )}
     </ul>
   </div>
 );
}

✏️ Conclusion

Optimistic UI, empowered by Remix's robust data handling and MSW's incredible mocking capabilities, allows us to build web applications that not only function correctly but also feel incredibly fast and responsive. Remix’s intelligent handling of data with loader and action functions, coupled with the granular control offered by useFetcher, makes optimistic updates remarkably straightforward to orchestrate. It elegantly manages the dance between immediate UI feedback and eventual server-side reconciliation.

This combination is an absolute game-changer for perceived performance and user satisfaction. Give it a try in your next Remix project, and let your users enjoy the instant gratification of an optimistically updated interface.

Seeding your database with Prisma ORM

ishan — Fri, 03 Mar 2023 13:51:01 +0000

Object Relation Mapper(ORM) is a technique of storing, retrieving, updating and deleting data from the database. ORMs let us define our models as classes that map to tables in a database.

When it comes to ORM there are many choices available to us like Sequelize, TypeORM, Knex, Drizzle and Prisma.

In this article we will cover Prisma, which is a top tier choice for ORM in your next application.

Prisma is an open source next-generation Node.js and TypeScript ORM. It describes itself as a “next-generation ORM” that makes working with databases easy for application developers.

It's is written in Typescript, which leads us to type-safe database schemas. Of course, everything needs to be well set to define what that database will look like. It abstracts developers from writing database queries, thus ensuring we write safe database access schemas.

The most awesome thing is the Prisma-client to set up and write database, model data, data validation, and describe the relationships between different data fields. Not only that it has a migration tool and a supercool GUI to visualize your data.

Tools provided out of the box:

Prisma Client: Auto-generated and type-safe Prisma query builder

Prisma Migrate: Migration system

Prisma Studio: A modern GUI for browsing and managing data in your database

Connect Prisma with DB

We will follow the documentation to get started with Prisma. You can read and also take a reference to the documentation.

For a demo we are using Prisma along with Typescript in our sample Node project connect with MongoDB instance in Railway.

We need a database connection string, we will get a MongoDB database connection URL from Railway here.

npx prisma init --datasource-provider mongodb

We will set the url field of the datasource block in our prisma schema to our recently created database connection URL.

Set, the url is set via an environment variable which is defined in .env:

DATABASE_URL="******"

Modeling data

We can start with modelling our data for our application. Prisma schema provides an intuitive way to model data. Add the following models to your schema.prisma


// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

model User {
  id            String    @id @default(auto()) @map("_id") @db.ObjectId
  name          String?
  image         String
  company       String
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  email         String    @unique
  emailVerified DateTime?
  password      String
}

model Products {
  id          String   @id @default(auto()) @map("_id") @db.ObjectId
  title       String   @unique
  description String
  price       String
  size        String
  quantity    Int
  image       String
  createdAt   DateTime @default(now())
}

enum Role {
  User
  Admin
  Buyer
  Seller
}

We created our data model.

We are building something like a marketplace where users can upload list of products to the Marketplace. And there are list of products which we want to seed the DB with along with the new user created.

We need to run the two commands so that we can setup the documents and tables needed for our application.

npx prisma generate

This command will generate the needed tables to store our data for our application using the data model we defined.

npx prisma studio

This will spin a GUI where we can take a look into when we have the tables and/or data inserted into our DB.

Adding Fake data

Before starting seeding our database we need some fake data. To generate some decent realistic fake data we are using two libraries.

Lets install them both.

npm i @ngneat/falso @faker-js/faker

We will also install a library to hash the fake user password that is created.

@types/bcryptjs bcryptjs

Let's create a new file and name it seed.ts

import bcrypt from 'bcryptjs';
import { randBetweenDate, randNumber, randProduct } from "@ngneat/falso";
import { faker } from "@faker-js/faker";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const main = async () => {
  try{
    await prisma.products.deleteMany();
    const email = faker.internet.email('ishan', 'manandhar', 'example.fakerjs.dev');
    const companyName = faker.company.companyName()
    const hashedPassword = await bcrypt.hash('my_secure_password', 10);
    await prisma.products.deleteMany(); //delete existing products
    const fakeProducts = randProduct({
      length: 300,
    });

    // cleanup the existing database
    await prisma.user.delete({ where: { email } }).catch(() => {
      // delete existing user found with same email
    });

    await prisma.user.create({
      data: {
        name: 'ishan',
        image: '',
        email: email,
        password: hashedPassword,
        company: companyName
      },
    });

    for (let index = 0; index < fakeProducts.length; index++) {
      const product = fakeProducts[index];
      const name = faker.commerce.productName();
      await prisma.products.upsert({
        where: {
          title: name,
        },
        create: {
          title: name,
          description: faker.lorem.paragraph() || product?.description,
          price: faker.commerce.price(),
          image: faker.image.abstract(640, 480, true),
          quantity: randNumber({ min: 10, max: 100 }),
          size: faker.random.numeric(),
          createdAt: randBetweenDate({
            from: new Date("10/07/2020"),
            to: new Date(),
          }),
        },
        update: {},
      });
    }
    console.log(`Database has been seeded. 🌱`);
  }
  catch(error){
    throw error;
  }
}

main().catch((err) => {
  console.warn("Error While generating Seed: \n", err);
});

Lets run the seed file with the command

npx prisma db seed

After sucessfully running the seed file we can head to our terminal and run npx prisma studio to see our data added to our documents.

Yes, we have done it!

Conclusion

Prisma is such an awesome ORM that has a best developer experience(DX), documentation, observability support and end-to-end TypeScript coverage we can ever get.

It has made working with databases feel so intuitive and straightforward from the data modeling, running, migrations, writing the queries, and integrating it with the API's.

You can learn more from the Prisma official docs here.

Happy Coding!

Webpack 5 Module Federation : Exchange code between applications

ishan — Mon, 27 Feb 2023 12:56:26 +0000

Module Federation is one of the most exiting feature that was introduced in Webpack 5 release dated 2020-10-10.

With this there has been a huge change on how we architect our modern application we build today.

What is Module Federation(MF)?

Module Federation(MF) aims to solve the fiction sharing of modules in a distributed system. To simplify things we can bring in modules of our code across multiple applications.

The code can contain :: state of the application, library dependencies that will be made available within a common registry managed by the Webpack container.

Module Federation allows a JavaScript application to dynamically load code from another application and in the process, share dependencies.
Zack Jackson (Creator of Webpack)

It’s important to note that this system is designed so that each completely standalone build/app can be in its own repository, deployed independently, and run as its own independent SPA.

💡 This is often known as Micro-Frontends, but is not limited to that.

Setting up Module Federation

We will take a look into how can we use MF in our demo React application. We will just start with create-react-app for simplicity.

First React App

mkdir applicaion01
cd applicaion01
npm init -y
npm install react react-dom --save
npm install @babel/core @babel/preset-env @babel/preset-react babel-loader css-loader html-webpack-plugin webpack webpack-cli webpack-dev-server --save-dev

With the above commands in place we can make our first change inside of package.json file

"scripts": {
  "build": "webpack",
  "start": "webpack serve --watch-files ./src"
}

Make sure you are in your current project directory. We will need a change the babel presets as below

{
  "presets": [
    "@babel/preset-env",
    "@babel/preset-react"
  ]
}

Lets start with our webpack.config.js file and past the code below

const HtmlWebpackPlugin = require("html-webpack-plugin");
const path = require("path");
const ModuleFederationPlugin = require("webpack/lib/container/ModuleFederationPlugin");
const deps = require("./package.json").dependencies;

module.exports = {
  mode: "development",
  resolve: {
    extensions: [".css", ".js", ".jsx"],
  },
  module: {
    rules: [
      {
        test: /\.s?css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              url: {
                filter: (url) => {
                  if (url.startsWith("data:")) {
                    return false;
                  }
                  return true;
                },
              },
            },
          }
        ],
      },
      {
        test: /\.jsx?$/,
        use: ["babel-loader"],
        exclude: /node_modules/,
      },
      {
        test: /\.(png|svg|jpg|jpeg|gif)$/i,
        type: "asset/resource",
      },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, "public", "index.html"),
    }),
    new ModuleFederationPlugin({
      name: "APP_ONE",
      filename: "remoteEntry.js",
      exposes: {
        "./app": "./src/components/App",
      },
    }),
  ],
};

In the code above we set up couple of loaders needed for our application. We named our (first) application application01 because we will be sharing code across multiple application/projects.

Let's continue with editing our new file app.js file.

import React from 'react';
import "./styles.css";

export default function App({ onChange }) {
  return (
    <>
      <input onChange={onChange} type="text" placeholder="Enter your address" />
    </>
  );
}

The above component App is the main microfrontend we will be exposing in our project.

We can add more components and expose them using webpack.config.js file which we will dive into

Lets edit our main file main.js where we will be importing the file we created before app.js into this file.

import {useState} from 'react';
import App from './app';
import "./styles.css";

export default function MainApp() {
  const [address, setAddress] = useState('');
  return (
    <>
      <h3>{ address ? <p>Your address {address}</p> : null }</h3>
      <App onChange={(e) => setAddress(e.target.value)} />
    </>
  );
}

With this in place we can see a input file where we could type our address inside and see the binding state changed.

Creating second React app

Lets create another project and name it application02

Second React App

mkdir applicaion02
cd applicaion02
npm init -y
npm install react react-dom --save
npm install @babel/core @babel/preset-env @babel/preset-react babel-loader css-loader html-webpack-plugin webpack webpack-cli webpack-dev-server --save-dev

We will also change our package.json file as we did before something like

"scripts": {
  "build": "webpack",
  "start": "webpack serve --watch-files ./src"
}

Also create a babel.config.json file alike config below

{
  "presets": [
    "@babel/preset-env",
    "@babel/preset-react"
  ]
}

Create our webpack.config.js file and paste the code below

const HtmlWebpackPlugin = require("html-webpack-plugin");
const path = require("path");
const ModuleFederationPlugin = require("webpack/lib/container/ModuleFederationPlugin");
const deps = require("./package.json").dependencies;

module.exports = {
  mode: "development",
  resolve: {
    extensions: [".css", ".js", ".jsx"],
  },
  module: {
    rules: [
      {
        test: /\.s?css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              url: {
                filter: (url) => {
                  if (url.startsWith("data:")) {
                    return false;
                  }
                  return true;
                },
              },
            },
          }
        ],
      },
      {
        test: /\.jsx?$/,
        use: ["babel-loader"],
        exclude: /node_modules/,
      },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, "public", "index.html"),
    }),
    new ModuleFederationPlugin({
      name: "applicaion02",
      remotes: {
        APP_ONE: "applicaion01@http://localhost:8080/remoteEntry.js",
      },
    }),
  ],
};

We have done the same process adding needful loaders to our application and setup our app remote as applicaion01

Let's go ahead to edit our app.js file inside of our src folder. Below are some changes

import { lazy, Suspense } from "react";
import "./styles.css";

const AppOne = lazy(() => import("APP_ONE/app"));

const App = () => {
  const [address, setAddress] = useState('');

  return (
    <>
      <h3>{ address ? <p>Your address {address}</p> : null }</h3>
      <div>
        <Suspense fallback={<span>Loading...</span>}>
          <AppOne onChange={(e) => 
 setAddress(e.target.value)} />
        </Suspense>
      </div>
    </>
  );
};

export default App;

We are making use of react lazy loading to load parts of our application. We are also importing suspense so that we could wrap our remote React micro app we created.

Where we have alike micro-frontend architecture going on.

We have successfully to this point imported modules from another app and used it inside of another application. We have implemented something basic, we just scratched the surface.

The awesome thing is this also works well with Server Side Rendering(SSR) means we can use this inside of any application/framework unless its using Webpack as a module bundler your code chunks.

Conclusion

We used Webpack 5 Module Federation to consume and share micro-frontend components. This brings a huge gap of possibilities using Federated Modules.

Reference readings

https://webpack.js.org/concepts/module-federation/

https://medium.com/swlh/webpack-5-module-federation-a-game-changer-to-javascript-architecture-bcdd30e02669

https://dev.to/marais/webpack-5-and-module-federation-4j1i

https://javascript.plainenglish.io/next-js-11-module-federation-and-ssr-a-whole-new-world-6da7641a25b4

Enums in Typescript explained

ishan — Sun, 12 Feb 2023 06:44:09 +0000

In the world of programming enumerated type(enum) is a data type consisting of a set of named values called elements, members, enumeral, or enumerators of the type.

What is Enums

An Enum in TypeScript is a well-defined collection of a limited number of cases. That is, we write down all possibilities and do not allow anything else.

In typescript enums keyword offers a way for us to define a finite set of values — usually as named constants in a strongly typed way.

In short enums are useful when setting properties or values that can only be a certain number of possible values.

Enums basic

To create a basic enum in typescript we could start with the enum keyword. We can specify the enum members like

enum AvailableLaunguages {
  EN = 'English',
  FR = 'français',
  DN = 'danish',
  NP = 'Nepali',
};

We have created a basic enum and named it AvailableLaunguages. To reference enum values, we would treat them as object attribute and access them using dot (.) notation.

console.log(AvailableLaunguages.EN); //English
console.log(AvailableLaunguages.FR); //français
console.log(AvailableLaunguages.DN); //Danish
console.log(AvailableLaunguages.NP); //Nepali

There is also the possibility of not assigning values to the enums we described.

Lets take another example

enum GameLevel {
  Beginners,
  Medium,
  Noob,
  Pro,
  Worldclass
};

By default, enums are numeric enums, i.e. GameLevel.Beginners is 0, GameLevel.Medium is 1, GameLevel.Noob is 2, GameLevel.Pro is 3, and GameLevel.Worldclass is 4.

Numeric enums are not strongly-typed to the values in the enum, but string enums are.

So, Enums are default to numbers if not assigned any values but it can also be assigned a string (or mix of both) if needed.

Using Enums as a datatype or Values

The flexibility of using enums are we could use it to store the data type of any enum defined or use it as a value.

const NewGamer : GameLevel = GameLevel.Beginners;

Here we defined a value with a variable declaration using NewGamer and its data type is same we defined before which is the Gamelevel enum, added as a data type to our NewGamer variable.

Using Enums inside interfaces

Let's create a simple interface for a Gamer.


interface Gamer {
  id: number;
  name: string;
  number: number;
  level: GameLevel;
}

const player: Gamer = {
  id: 1,
  name: 'ishan',
  number: 0,
  level: GameLevel.Medium
}

console.log('player', player);

As we can see we also stated the level of the gamer is the type of GameLevel.

We added a constraint to the value of level.

Enums are a type that can make code more readable and maintainable, where the meaning of the value of a variable is not apparent. This comes in handy when we are tasked with making comparisons between or among values from an enum, or even in their regular use.

TypeScript enums make it easier to document intent or to create a distinct set of cases.

https://www.typescriptlang.org/docs/handbook/enums.html

Thank you!

How to Setup a Free MongoDB database on Railway

ishan — Fri, 10 Feb 2023 09:34:49 +0000

Since Heroku does not offer any more free plans dev are in search of better platform to host or use a free service for their application.

Railway is an awesome alternative If you are wondering about where can you use a cloud-based storage Database for your application using MongoDB.

You can use Railway for it.

Railway is a deployment platform where you can provision infrastructure, develop with that infrastructure locally, and then deploy to the cloud.

You can also host an entire application on Rail way. They do have a free generous plan covering

Max to 512 MB of RAM
Shared vCPU capacity
Up to 1 GB of Disk (Shared between plugins)

This would be enough for our starter projects but if you are planning more big please head to their pricing page.

Setup a Free MongoDB cloud instance

Head to Railway's dashboard in your browser. You can start from scratch or with a starter template or without entering your credit card information.

Access your database credentials

Below you are presented with the connection string you can use to connect your application.

You can click on your project and then click the Connect tab to show your database URL.

It was this easy indeed!

Conclusion

If you want to learn more about Railway you can get into their documentation here to get started for your deployment.

Railway aims to be the simplest way to develop, deploy, and diagnose issues with your application. They also offer lot of starter templates so that you can fire off any project just few clicks away.

Railway has excellent examples of starter templates for various app builds, including Next.js and Prisma, Node, Blitz.js, Deno, Hasura, Flask, Express, and more.

You can find it here.

Thank you!

Building a NodeJS REST API using Express, MongoDB, Prisma with Typescript

ishan — Mon, 06 Feb 2023 12:25:01 +0000

Let's build a full-stack RESTful API with NodeJS.

We will be creating Marketplace API using Express as our backend framework of choice. We will be communicating with the MongoDB database using Atlas on the cloud. All of this will be made easy with Prisma as an ORM with Typescript.

mkdir marketplace-api
cd marketplace-api
npm init -y

Install dev dependencies

npm i -D @types/node ts-node @types/express prisma typescript tcs-watch

Install app dependencies

npm i express dotenv @prisma/client

Initializing Prisma

npx prisma init

Generating Prisma Schema

npx prisma generate

Create a tsconfig.json file in the root and add the following configuration to it:

{
  "compilerOptions": {
    "lib": ["esnext"],
    "module": "CommonJS",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  }
}

Below is our package.json file in case if you have missed anything down the road.

{
  "name": "marketplace-api",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node/dist/src/index.js",
    "dev": "tsc-watch --onSuccess \"node ./dist/index.js\"",
    "watch": "npx ts-node index.ts",
    "build": "tsc",
    "seed": "ts-node prisma/seed.ts"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@types/express": "^4.17.17",
    "@types/node": "^18.11.19",
    "prisma": "^4.9.0",
    "ts-node": "^10.9.1",
    "tsc-watch": "^6.0.0",
    "typescript": "^4.9.5"
  },
  "dependencies": {
    "@prisma/client": "^4.9.0",
    "dotenv": "^16.0.3",
    "express": "^4.18.2"
  }
}

Creating Models

After installing all the dependencies needed for our application we can start with creating Schema for our Application.

We are using MongoDB as our database. We have created the DB connection string from Mongo Atlas. You can generate it from here.

You can use a .env file to list all your environment variables need for your application.

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

model User {
  id       String     @id @default(auto()) @map("_id") @db.ObjectId
  email    String     @unique
  name     String?
  role     Role       @default(User)
  products Products[]
}

model Products {
  id        String   @id @default(auto()) @map("_id") @db.ObjectId
  title     String
  imageURL  String
  selling   Boolean  @default(false)
  seller    User     @relation(fields: [sellerId], references: [id])
  sellerId  String   @db.ObjectId
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

enum Role {
  User
  Admin
  Buyer
  Seller
}

We are building an API endpoint which will lets users to list the products they want in the marketplace. They can mark them selling when they are ready to sell.

Each seller will have a product image, is generated by default, title and is selling status.

Creating Express server

import "dotenv/config";
import express from "express";

const app = express();
const PORT = 3000

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
});

After we add this inside of src folder we can run this with command

npm run dev

This will compile our typescript application and serve taking the filepath described in our scripts inside package.json file.

Seeding DB with User

Create a new file named seed.ts in your prisma folder. This would look something like

You can learn more from official doc here.

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

async function run() {
  const user = await prisma.user.upsert({
    where: { email: "cody@mail.com" },
    update: {},
    create: {
      name: "Coder Codes",
      email: "cody@mail.com",
    },
  });

  console.log({ user });
}

run()
  .catch((e) => {
    console.log(e);
    process.exit(1);
  })
  .finally(async () => {
    await prisma.$disconnect();
  });

npx prisma db seed

Running this command will create a new user for us in the database. with a new name and a given email and disconnect.

Creating API endpoints

With this in place we are in the good position to start building our API endpoints. We will heavily make the use of awesome Prisma ORM features which will help us to query our database.

Creating new product

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

// create a product
app.post("/products", async (req, res, next) => {
  console.log(req.body, '************'); //Take a look into request object here
  try {
    const newProduct = await prisma.products.create({
      data: { sellerId: 1, ...req.body },
    });

    res.json({ newProduct });
  } catch (error: any) {
    next(error.message);
  }
});

Here we made a post request to the given url which will create a new products inside of our products document. This will be a seller id of 1 and it takes other data from request.body

Get all products

To get all the list of products we can use the .get() method from express which will receive a callback function using the findMany() method from prisma to return all JSON data of products from our DB.

app.get("/products", async (req, res, next) => {
  try {
    const allProducts = await prisma.products.findMany();
    res.json({ allProducts });
  } catch (error: any) {
    next(error.message);
  }
});

Get a product by ID

We can add a query params into our URL endpoint. There we could access the id with req.params.id this would eventually return a JSON object which will match the ID that is passed in.

app.get("/products/:id", async (req, res, next) => {
  try {
    const singleProduct = await prisma.products.findUnique({
      where: {
        id: req.params.id,
      },
    });

    res.json({ singleProduct });
  } catch (error: any) {
    next(error.message);
  }
});

Update a product

We can use a PATCH request which will pass in the ID from teh request query.

app.patch("/products/:id", async (req, res, next) => {
  try {
    const product = await prisma.products.update({
      where: {
        id: req.params.id,
      },
      data: req.body,
    });

    res.json({ product });
  } catch (error: any) {
    next(error.message);
  }
});

Delete a Product

Using a DELETE request we can find the product matching in the passed parameter ID and delete with the help of Prisma handy delete() method.

app.delete("/products/:id", async (req, res, next) => {
  try {
    await prisma.products.delete({
      where: {
        id: req.params.id,
      },
    });

    res.sendStatus(200);
  } catch (error: any) {
    next(error.message);
  }
});

Get Single user Product

We can get a user with an ID with the findUnique() method available to us. Taking in the where key to further know the ID we are dealing with from request object.

app.get("/users/:id/products", async (req, res, next) => {
  try {
    const usersWithProducts = await prisma.user.findUnique({
      where: {
        id: req.params.id,
      },
      include: {
        products: {
          where: {
            selling: true,
          },
        },
      },
    });

    const products = usersWithProducts?.products;

    res.json({ products });
  } catch (error: any) {
    next(error.message);
  }
});

Conclusion

We have successfully created a simple API endpoint for our Marketplace application. If you want to delete a record with relation, you can read more about Cascading deletes.

I hope this is useful in understanding how we could create API using Express, MongoDB, Prisma ORM with Typescript.

Thank you!

Learning References

Deploying Remix application to Cloudflare Pages

ishan — Sat, 04 Feb 2023 09:37:59 +0000

Cloudflare Pages is a solution for hosting our static web applications. Static in a sense, but made dynamic through pulling in data at build time and further layering a dynamic experience in the browser.

In December 2021, Cloudflare announced the beta of Cloudflare Pages: a fast, secure, and free way for frontend developers to build, host, and collaborate on Jamstack sites.

By making requests to APIs, whether self-hosted or through the number of services from content management or Headless CMS for authorization, we can give just as dynamic of an experience as one would expect from a server rendered approach.

When we are in need to deploy your JAMstack application with limited workflow setup and configuration, Cloudflare is a excellent choice that will have our application up and running within minutes.

Let's dive into how ca we deploy a Remix application with Cloudflare Pages. Not only that we will also take a look into branching and preview branch deployments. This is one of a supercool 😎 feature of Cloudflare Pages features.

I assume you have an account created in Cloudflare Pages. If you don't have please head to the dashboard.

Creating a Remix Application

We will first begin creating our project fullstack app with Remix, with the command below

npx create-remix@latest

Select Cloudflare Pages for our deployment target.

Lets go ahead and run the Remix application with the command

npm run dev

This should spin up a local server with a port running(probably 8788).

Pushing to Github

We can do the needful changes and push our progress to Github. Where we will push our code repository there.

So create an new empty project in Github. And use the commands to push changes into Github.

One by one you needed to the add the commands. The commands are also listed below for your convenience

echo "# remix-cloudflare-deploy" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/***your_username***/remix-cloudflare-deploy.git
git push -u origin main


git add .
git commit -m 'second commit'
git push origin main

After all the commands you should see our application is inside of github.

Creating a project in Cloudflare Pages

Inside your logged in Cloudflare dashboard. You can navigate into Pages and create a new project from there.

After you have connected to Github through Cloudflare you must see the interface below. With active Begin setup button.

Deployment (main)

Please note you might need to give Cloudflare permission to access your file or access all files.

You can select Remix from the Framework of choice and everything will be fine as a default. After we deploy we should be presented with a screen of URL of deployment.

Deployment (branch)

Let's add a preview branch deployment to our projects. We will run the following command to checkout into a new branch and deploy a preview branch.

We will name our branch preview

git checkout -b 'preview'   
git commit -m 'preview test branch'
git push origin preview

We can click on the orange dot to see the deployment in progress. We will create this into a Pull Request (PR). After a successful PR is created for a desired target branch we can head to our Dashboard.

We can now see there are two URL that are being served in the dashboard. And both have their own URL.

This is really handy if we want to test some features in a experimental mode, sync with other team members, share a link and more benefits included.

Conclusion

Cloudflare full-stack Pages are a great choice for developers looking to deploy applications via a single git commit.

Even we have a preview links which is really helpful.

In this article, we covered how to deploy Remix application into Cloudflare Pages from GitHub.

I hope this is helpful. Happy Coding!

Custom Schema Validation in TypeScript with Zod

ishan — Tue, 31 Jan 2023 13:59:31 +0000

Zod is a schema validation library. Its goes well with building Typescript projects. Zod has zero dependencies which means that you can install and use Zod without any other libraries, and it will help you keep your bundle size less bulky.

In this article we will cover how can you use a basic to custom validation logic for your schema parsing validation using Zod. This will just cover some basic way to add a custom validation logic in your schema created.

Why need a schema validation?

Schema validation is the process of verifying the data structure to a pre defined set of schema specification. We can use it to ensure the validity of input data, as well as to document and enforce your application’s data structures.

We might need to add a parsing library to our application mainely for the reasons below

Parse form data before sending to the server
Parse data before sending back out to the client
Parse data in functions around our application
Parse data at the API boundary before sending to the DB
Parse data from an third-party data source

Zod makes it extremely easy to create simple schemas to validate primitives, objects, type inference from the schemas, composing schemas and more.

Installing

We will start a barebones project with the following commands.

mkdir zod-custom-validation
cd zod-custom-validation
npm init -y
npm i zod
npm i tsx --save-dev

After we have install all the needful packages to get start with typescript compilation we need to tweak this to our package.json file

  "scripts": {
    "validation": "tsx watch validation.ts"
  }

Here we specify we will be running a file name validation.ts which we will be creating to experiment with zod validation.

Let's create a validation.ts file in our root folder with commands below

touch validaton.ts
npm run validaton

Basic Validation

To start with a basic validation we could start with having a User fields. This would something like

id would be a type of number
name would be a string
portfolio would be a string and should be a url
salary would be a number and is nullable/optional

import z from 'zod';

const schema = z.object({
  id: z.string({
    required_error: "ID is required",
    invalid_type_error: "ID must be a string"
  }),
  name: z.string({
    required_error: "Name is required",
    invalid_type_error: "Name must be a string"
  }),
  portfolio: z.string({
    required_error: "portfolio is required",
    invalid_type_error: "portfolio must be a string"
  }).url(),
  salary: z.number({
    invalid_type_error: "salary must be a number"
  }).optional(),
})

type ValidatePayload = z.infer<typeof schema>

const payload: ValidatePayload = {
  id: "35625",
  name: "New user",
  portfolio: "https://dev.to/isnan__h/custom-schema-validation-in-typescript-with-zod-5cp5"
}

const parseSchema = (props: ValidatePayload) => {
  return schema.parse(props)
}

const result = parseSchema(payload)
console.log(JSON.stringify(result))

In the above snippet we defined a schema with a set of rules. These rules must me passed to execute our validation error free.

To check this we can pass a url that is not a URL then it would fail with a error needs portfolio to be a URL.

Custom Validation

To add a custom validation can be achieved with method provided to us .superRefine() and we have the .refine() method, The refine method is used to provide custom validation logic via refinements.

const schema = z.object({
  name: z.string({
    required_error: "Name is required",
    invalid_type_error: "Name must be a string"
  }),
  phone: z.number({
    required_error: "Phone number is required",
    invalid_type_error: "Phone must be a number"
  }),
  confirmPhone: z.number({})
}) .refine((data) => data.phone === data.confirmPhone, {
  message: "Phone numbers dont match"
});

const payload: ValidatePayload = {
  name: "New user",
  phone: 24562454453465,
  confirmPhone: 24562454453465
}

const result = parseSchema(payload)
console.log(JSON.stringify(result))

This is a basic implementation of how we can add custom logic using the refine() method. In the above example we are making sure the phone and confirmPhone needs to be both same.

Conclusion

We could make the use of Zod to verify the schema we define in our application. These primitives can be chained together to build a very robust and flexible schema design for your application.

Having a runtime validation is always a needed thing for our application, as it makes our code more readable and sanitizes user inputs before redirecting them to the server.

For more information on Zod, be sure to check out the excellent documentation on their site.

You can find there more detailed examples of how to use all of the functionality that Zod has to offer.

https://zod.dev/?id=table-of-contents
https://zod.dev/?id=error-handling

Happy coding!

Building Subscription Application with Cloudflare Worker KVs

ishan — Mon, 23 Jan 2023 12:23:22 +0000

Cloudflare workers is a service that lets us to deploy to the Cloudflare network distributed around 200 cities around the world. With this we are using the edge functions which servers us very low latency and is near to us geographically distributed.

Among many of the services provided by Cloudflare we are focusing on Workers Key Value(KV) Store. We will bring here official KV definition from Cloudflare docs

Workers KV is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access. KV supports exceptionally high read volumes with low latency, making it possible to build highly dynamic APIs and websites that respond as quickly as a cached static file would. While reads are periodically revalidated in the background, requests which are not in cache and need to hit the centralized back end can see high latencies.

Official docs

What will we build

We will build a simple API where we will be interacting with the KV to get all KV, get a one KV, put new KV storage.

We will build a mini subscription application which lets us store the email, status(free/premium), id in a KV Store. This will help us to know which users belongs to the free plan or premium plan.

We can start by installing Wrangler if you dont have it in your local machine. Its a CLI with helps us to create workers project locally.

npm install -g wrangler

After installation we are ok to create our worker project. Where we will be using a Javascript to write all the logic currently. But you can use the official templates provided with many launguage as your choice.

wrangler init project-name

We can now start by creating a new folder and name it utils. Here we can add any functionalities which can help us interact with the KV methods.

Installing dependencies

We will use a bare minimum dependencies as possible. Lets add two packages with command below

npm i itty-router nanoid

itty-router is the routing library which we will use.
nanoid is the library we will use for generating unique ids.

Generating new KV Namespace

To get started with KV Storage you need a namespace to be generated. Below are the commands you will need.

npx wrangler kv:namespace create "SUBSCRIPTIONS"

npx wrangler kv:namespace create "SUBSCRIPTIONS" --preview

The--preview option informs Wrangler it’s for preview only, which is specifically for development mode.

You might need to create a cloudflare account to generate your workers id. You can get it from thedashboard.

Below is the example of updated wrangler.toml file with the information needed

name = "kv-worker-demo"
type = "webpack"
main = "src/index.js"
account_id = "**********"
workers_dev = true
compatibility_date = "2023-01-21"
webpack_config = "webpack.config.js"
kv_namespaces = [
    { binding = "SUBSCRIPTIONS", id = "*********", preview_id = "*********" }
]

Creating routes

import { Router } from "itty-router";

const router = Router();

router.get("/api/subscriptions", async (req) => {
  return new Response("Workers running...", { status: 200 });
});

router.get("*", () => new Response("Not found", { status: 404 }));

export const handleRequest = (request) => router.handle(request);

We will make the use of router from our itty-router library. and create a get request route for two basic endpoint where we have a general route with a astrix and /api/subscribers to interact with our workers listening.

Get all subscribers

To get all the records of the subscribers we could make the use of the namespace we created and return empty if we dont find one.

import { KV_KEY_ID } from '../handler'

export const getAllSubscriptions = async () => {
  let subscriptions = await SUBSCRIPTIONS.get(KV_KEY_ID)
  if (subscriptions === null) {
    return []
  }
  return JSON.parse(subscriptions)
}

export const KV_KEY_ID = 'subs'

router.get('/api/subscriptions', async req => {
  const allSubs = await getAllSubscriptions()
  return new Response(JSON.stringify(allSubs))
})

Creating new subscriber

To create a new subscriber we need a POST request. This would first take in a request body and calls a function addSubscriptions taking in the content as a parameter.

router.post('/api/subscriptions', async req => {
  let content = await req?.json?.()
  if (content == undefined) {
    return new Response('Please provide a request body.')
  }
  content['id'] = nanoid()
  let subs = await addSubscriptions(content)
  return new Response(JSON.stringify(subs))
})

We need to create a addSubscriptions function which will make a call to our previous function and pushes a new item into that array.

Lastly we need to make a PUT request to our worker to notify the change with a .put() method available to us.

export const addSubscriptions = async (sub) => {
  let subscription = await getAllSubscriptions()
  subscription.push(sub)
  await updateSubscriptions(subscription)
  return sub
}

export const updateSubscriptions = async (sub) => {
  await SUBSCRIPTIONS.put(KV_KEY_ID, JSON.stringify(sub))
}

Getting one subscriber

We can also get the request parameter and find the needed KV from our store.

And finally return a stringified version of the id that is passed in to us from the request object.

router.get('/api/subscriptions/:id', async req => {
  let allSubs = await getAllSubscriptions()
  let subID = allSubs.find(a => a['id'] == req.params?.id)
  if (!subID) {
    return new Response('This ID is not matched')
  }
  return new Response(JSON.stringify(subID))
})

This is how we can make the use of Cloudflare KV for our data storage solution makes it handy. We used a multiple, kv_namespaces accepts an array of objects.

We could add still more functions where we could use the delete, listing only keys, Time to live(TTL), Expiring keys and many awesome features baked in.

You can learn more from here

You can find the complete code repository here.

Happy coding!

Reading references

Workers KV
How KV Works
Durable Objects
https://youtu.be/dei8fOR_Of8