Forem: Kirby Aguilar

Deploying a Rails 7 + React app to AWS via Dokku

Kirby Aguilar — Tue, 08 Oct 2024 12:37:47 +0000

Dev work is tough. Most of the time, deployment is even tougher, by a mile.

My previous workplace was run by a team that lacked experience in getting an app from zero to production. We had a starter react + rails app in our hands, but the details of the final step--putting our app online for users to consume--was amorphous at best. Our whiteboard was inked with a "let's use Elastic Beanstalk," so I was told to do just that.

Attempting to deploy to EBS in 2024 was nothing short of a nightmare. Every step took 20 minutes, where you prayed that nothing would fail (but something would fail every time). You couldn't even read the logs!

A few days passed, and I was unable to get a starter rails API app on EBS, much less our actual app. I started looking into taking a different approach.

Enter Dokku 🐋

We looked into what was popular in 2022-2024 (hatchbox, render, heroku, etc) and Dokku stood out. It was popular, it was open source, it ran on lower-end machines, it was easy to set up, and we could stay on AWS if we put it into EC2 instances. It looked very, very promising.

Of course, despite its popularity, there were very few guides for deployment, and practically no guides for our exact setup (AWS, React, Rails). Figuring out how to fulfill the promises was something I'd have to do on my own.

What we want to achieve in this guide

Set up an app with react/vite as a frontend, and ruby on rails as a backend. The sample app should be something minimal: one page on the frontend, with a demonstration that the frontend can call the backend, which should be connected to a database.
Deploy said app to AWS, while highlighting considerations re: dokku and infrastructure

By the way, if you're reading this and following along, I'm assuming you have some knowledge of how to operate within AWS. I won't be going into beginner-level detail for infrastructure-related steps

The app

Details re: the app aren't the focus of this guide, so it's recommended to just clone this GitHub repository and create a new master key.

If you're interested in how the app was set up, you can take a look at the README in the source code, which also covers the prerequisite installs for doing so.

Details that you should know about the app

To connect rails and react, we leverage the fact that npm run build compiles everything into a singular index.html. We place this in Rails' public/ directory. Settings for this can be found within frontend/vite.config.ts and frontend/package.json.

All routing within the app falls under two categories:

(1) API routes, which start with /api. Requests to these are handled by the appropriate rails controller
(2) Every other URL pattern is caught by the line get '*path', to: 'static#frontend' in routes.rb. Our static page controller redirects the request to the aforementioned index.html, after which something like react-router can take over.

Most importantly: we need to create a package.json within the rails folder. Like Heroku, Dokku operates on buildpacks, which are sets of instructions to build your app. These work off of activation conditions, e.g. your app is a ruby app if there is a Gemfile in the root folder.

Because our app is React + RoR, we need to use both the node and ruby buildpacks. It's surprisingly very hard to just specify that everything under the frontend directory is the node app, so we instead "trick" Dokku by providing a package.json in our root directory. This file tells Dokku to cd to the frontend directory and build from there.

As for expected behavior from the app, we want our root URL to point to a page with hello world, which upon loading will query our database for a list of employees and display the JSON in the frontend. Something like this:

High level infrastructure

The infrastructure for the project is pretty simple: end users send a request to a load balancer, which routes the request to an EC2 instance within an auto scaling group. Each individual EC2 instance is powered by Dokku, with a container running our rails + react app. We also have one central RDS database that the EC2 instances connect to.

Step-by-step infrastructure setup

Create a VPC

Create a VPC along with its associated resources. Make sure to have two availability zones with one public subnet each. Do not create private subnets. Do not add NAT gateways.

Create an RDS Postgres database

Standard create -> PostgreSQL database

The free tier template and defaults should be enough. No need to connect to a specific ec2 instance because we'll connect later.

Create/edit security groups to allow communication between the RDS db and EC2 instances

First security group (db's security group):

allow postgresql inbound from second security group
this security group is assigned to the RDS DB

Second security group (EC2-to-db-name):

allow postgresql outbound to first security group
this security group is assigned to EC2 instances

Store the necessary secrets in AWS secrets manager

Secrets to store:

RDS access credentials
SSH key to be used with dokku
RAILS_MASTER_KEY
Github personal access token of an account with read access to your repo

Create an IAM role to access secrets

IAM role should:

be for the EC2 AWS service
have the AmazonRDSFullAccess permission
have the SecretsManagerReadWrite permissions

This IAM role will be part of the launch template.

Create a security group for the EC2 instances

Inbound:

SSH only from your IP
HTTP from anywhere (allow web traffic)

Outbound:

IPv4, all traffic

Create a launch template

launch template instance parameters:

auto-scaling guidance: true
AMI: ubuntu-22.04
instance type: t2.small (Dokku says it runs on anything with 1GB memory and higher, but I've found that it stalls hard unless you have at least 2GB)
subnet: do not include in launch template
security group: use security groups from above
- auto-assign public IP: enable
storage: 24GB of gp2 volume type
advanced details, IAM: use IAM from earlier
advanced details, user data: we use a shell script. The source code will be in the same directory as this README.

Create an auto scaling group

Use the prior launch template. Select the VPC you created earlier. For the subnet, select the public subnets made available through creating the VPC.

While creating an ASG, you can attach it to a new load balancer. The load balancer should be:

An application load balancer
Internet-facing

This process will also prompt you to create a target group.

Enable health checks, and set the health check grace period + default instance warmup to 900 seconds (15 minutes).

Scaling: minimum capacity 1, maximum capacity 4

Instance maintenance policy: use the "availability" template

Enabling HTTPS (optional)

To enable HTTPS, request a certificate from AWS certificate manager on the domain. We assume that the domain is managed through AWS's route 53.

This certificate will be attached to the load balancer. This can be done through setting the LB's default SSL/TLS certificate under the LB's listeners and rules.

Make sure to adjust security groups such that HTTPS communication is allowed.

EC2 launch script and dokku settings

The EC2 launch script goes through dokku setup (and the installation of everything else you need in the instance). This should run automatically if set in your launch template's user data section, but I recommend booting up an instance and running things manually to see what the setup process is like.

Output for the EC2 launch script can be found in /var/log/cloud-init-output.log.

Notes:

Some of this may be slightly outdated (e.g. the dokku version), so feel free to use updated version of the commands
Replace ror-react-dokku with your project name
Replace fields like your-rails-master-key with the appropriate secret ID that you provided in secrets manager
We also make some assumptions re: the structure of secrets under secrets manager, so this may need some tweaking depending on how you set yours up

#!/bin/bash

# aws cli prerequisite
sudo apt-get install unzip

# aws cli installation
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
sudo unzip awscliv2.zip
sudo ./aws/install

# confirm aws installation
aws --version

# install dokku
wget -NP . https://dokku.com/install/v0.33.8/bootstrap.sh
sudo DOKKU_TAG=v0.33.8 bash bootstrap.sh

# set up SSH key using secrets manager
aws secretsmanager get-secret-value --secret-id your-ssh-key-in-secrets-manager --query SecretString --output text | jq -r '.["ssh-key"]' | sudo dokku ssh-keys:add admin

# set dokku domain to public IP of EC2 instance
dokku domains:set-global $(curl -s http://checkip.amazonaws.com)

# create app
dokku apps:create ror-react-dokku

# enable domains
dokku domains:enable ror-react-dokku

# set buildpack
# note that the nodejs buildpack MUST come before the ruby one
dokku buildpacks:add ror-react-dokku https://github.com/heroku/heroku-buildpack-nodejs
dokku buildpacks:add ror-react-dokku https://github.com/heroku/heroku-buildpack-ruby

# set rails master key
dokku config:set ror-react-dokku RAILS_MASTER_KEY=$(aws secretsmanager get-secret-value --secret-id your-rails-master-key --query SecretString --output text | jq -r '.RAILS_MASTER_KEY')

# set NODE_ENV to development
# this is required to successfully build during deploy
dokku config:set ror-react-dokku NODE_ENV=development

# set db related environment variables
dokku config:set ror-react-dokku DB_NAME=postgres
dokku config:set ror-react-dokku DB_PORT=5432
dokku config:set ror-react-dokku DB_HOST=$(aws secretsmanager get-secret-value --secret-id your-db-credentials --query SecretString --output text | jq -r '.["host"]')
dokku config:set ror-react-dokku DB_USERNAME=$(aws secretsmanager get-secret-value --secret-id your-db-credentials --query SecretString --output text | jq -r '.["username"]')
dokku config:set ror-react-dokku DB_PASSWORD=$(aws secretsmanager get-secret-value --secret-id your-db-credentials --query SecretString --output text | jq -r '.["password"]')

# port forward http
dokku ports:add ror-react-dokku http:80:5000

# remove nginx default page and restart nginx (without this, nginx page will show on your root route)
sudo rm /etc/nginx/sites-enabled/default
dokku nginx:stop
dokku nginx:start

# configure git auth to connect to private repository
dokku git:auth github.com your-selected-github-user-username $(aws secretsmanager get-secret-value --secret-id your-personal-access-token --query SecretString --output text | jq -r '.["PAT"]')

# allow remote repository host
dokku git:allow-host github.com

# pull from the repository and build
dokku git:sync --build ror-react-dokku https://github.com/yourOrganization/ror-react-dokku main

Note that we're using git:sync / git deployment to get the app instead of something like git push dokku main -- this is a more CI/CD friendly approach, where your pipeline can just ssh into each instance and run git:sync --build after obtaining the necessary permissions

...and that should be it! Once your ASG instances are up and running (give them about 10 minutes), you can get the URL for your load balancer and see your app on the open web.

As mentioned earlier, for automated deployment, you'll preferably want to continue by configuring circleCI / github actions to obtain the ASG's instance IDs. From there, you can get their public IP addresses, SSH into them one by one and run git:sync --build.

Recommendations for the future of this guide

Use terraform or similar
Elaborate re: setting up a CI/CD pipeline for this project

Final words

The contents of this guide synthesize the hardest, most engineer-y thing I did during my last position. In the span of a workweek and a half, I went from knowing very little about infrastructure and deployment to being able to set up the entire deployment process of our app.

There's a lot of value in hacking things together purely by yourself, but I also know a well-meaning guide from an internet stranger can be an absolute lifesaver. My hope is that this reaches even one person who's trying to do the same thing and not knowing how to do so.

References

The absolutely golden Dokku official documentation
sayadi's GitHub gist for obtaining for SSH-ing into an EC2 instance from CircleCI, for those who want to figure out CI/CD

Reusable form inputs with React Hook Form and TypeScript

Kirby Aguilar — Mon, 07 Oct 2024 18:43:53 +0000

When it came time to introduce a form validation framework to my previous company's app, we actually settled on TanStack Form. We took one swing at it, and immediately felt that the syntax was not for us. Sorry Tanner.

So we went back to the drawing board, and React Hook Form it was! One of us made a proof of concept by integrating it with our login form. It worked and it looked good, so the decision was made to continue using the library.

What we overlooked

What no one realized at the time was that our login and signup forms were the oldest forms in the entire app. Hence, they were the only ones not using our reusable <FormInput> components, which we used everywhere else. They looked a little bit like this:

// OldDeprecatedUncoolLoserFormInput.tsx

const FormInput: React.FC<FormInputProps> = ({
  type,
  inputName,
  labelText,
  isRequired,
  isDisabled,
  value,
  onChange,
}) => {
  return (
    <div className="flex flex-col gap-1">
      <label htmlFor={inputName} className="text-xs">{labelText}{isRequired && '*'}</label>
      <input type={type} id={inputName} name={inputName}
        className="input input-sm input-bordered"
        value={value}
        onChange={onChange}
        required={isRequired}
        disabled={isDisabled}
      />
    </div>
  );
}

It's no surprise that we couldn't use these as-is with RHF. Below is a comparison of the two:

{/* Here's how we used our old form inputs */}
<FormInput
  type="date"
  inputName="arbitraryFieldName"
  labelText="arbitrary field name"
  value={someFormData.arbitraryFieldName}
  onChange={someOnChangeInputFunction}
/>

{/* ..and here's an example from the RHF docs. When working with RHF, you need to pass in register to the input tag */}
<form onSubmit={handleSubmit(onSubmit)}>
  <input defaultValue="test" {...register("example")} />
</form>

Our forms, our onChange handlers for the forms' inputs, and the inputs themselves weren't built to work with RHF. Some major refactoring was in order. This responsibility fell onto me. Surprisingly, there were very few guides that actually went into solving this problem. Do people just not make reusable form inputs with RHF?

As we go on to mention in the references, this guide has adapted a lot from Keionne Derousselle's blog post, which was critical in solving this problem when I first encountered it. This guide is meant to be a more condensed (and slightly updated) version to its predecessor.

What we want to achieve

Create a new, reusable form input component that works with RHF
Disentangle inputs from the new reusable form input component. This means creating an <Input> component separate from <FormInput>
At the same time, we want a more robust <FormInput> that can show errors and accept class names for styling
We also want to demonstrate how one might tie RHF, RHF resolvers and react-query together.

Skipping to the end

If you're in a hurry and want a bird's eye view of the code without any of the explanations, you can go straight to the GitHub repository for this project.

Other tools we'll work with

Besides RHF and TypeScript, we'll be working with Vite, Tailwind CSS, react-query, zod, and classnames.

Project setup

$ npm create vite@latest reusable-rhf-form-inputs -- --template react-ts
$ cd reusable-rhf-form-inputs && npm install
$ npm install react-hook-form @hookform/error-message 
 @hookform/resolvers @tanstack/react-query zod classnames

# remove boilerplate files that we do not need 
$ cd src && rm -rf assets/ App.css index.css && cd ..

You can opt to follow the regular installation instead if you'd like, but for this guide we'll be using the tailwind CDN installation:

<!-- slot this into your <head> at src/index.html -->
<script src="https://cdn.tailwindcss.com"></script>

Let's edit some starter files as well:

// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import App from './App'

// used later for react-query
const queryClient = new QueryClient();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </StrictMode>,
)


// src/App.tsx
export default function App() {
  return (
    // confirm that tailwind is installed
    <h1 className="text-indigo-500">Hello world!</h1>
  )
}

We're ready to start! Let's carry on.

The `<Input>` Component

We start by defining a generic input component that isn't necessarily tied to an RHF form. We'll create our <FormInput> later based on this.

import { forwardRef, DetailedHTMLProps, InputHTMLAttributes } from 'react';
import classNames from 'classnames';

export type InputType = 'text' | 'email' | 'date' | 'time' | 'datetime' | 'number';

export type InputProps = {
  id: string;
  name: string;
  label: string;
  type?: InputType;
  className?: string;
  placeholder?: string;
} & DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>;

export const Input: React.FC<InputProps> = forwardRef<HTMLInputElement, InputProps>((
  {
    id,
    name,
    label,
    type = 'text',
    className = '',
    placeholder,
    ...props
  },
  ref
) => {
  return (
    <input
      id={id}
      ref={ref}
      name={name}
      type={type}
      aria-label={label}
      placeholder={placeholder}
      // change this to however inputs should be styled in your project
      className={classNames(
        'block w-full px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:border-indigo-500 placeholder-gray-400 transition',
        className
      )}
      {...props}
    />
  );
});

We can change our App.tsx to show the changes we've made so far:

// src/App.tsx

import { Input } from "./components/Input";

export default function App() {
  return (
    <div className="w-96 p-4">
      <h1 className="text-indigo-500 mb-4">Form with basic inputs</h1>

      <form className="flex flex-col gap-2">
        <Input id="first_name" name="first_name" label="first_name" />
        <Input id="employee_number" name="employee_number" label="employee_number" type="number" />

        <button type="submit" className="rounded-md text-white bg-blue-500 hover:bg-blue-600 p-2">Submit</button>
      </form>
    </div>
  )
}

You should be able to run npm run dev and see our inputs in action.

`<FormInput>` and the types that come with it

Here's our <FormInput> component:

// src/components/FormInput.tsx

import {
  Path,
  UseFormRegister,
  FieldValues,
  DeepMap,
  FieldError,
} from "react-hook-form";
import { ErrorMessage } from "@hookform/error-message";
import { Input, InputProps } from "./Input";

export type FormInputProps<TFormValues extends FieldValues> = {
  name: Path<TFormValues>;
  outerDivClassName?: string;
  innerDivClassName?: string;
  inputClassName?: string;
  register?: UseFormRegister<TFormValues>;
  errors?: Partial<DeepMap<TFormValues, FieldError>>;
  isErrorMessageDisplayed?: boolean;
} & Omit<InputProps, 'name'>;

const FormInput = <TFormValues extends FieldValues>({
  outerDivClassName,
  innerDivClassName,
  inputClassName,
  name,
  label,
  register,
  errors,
  isErrorMessageDisplayed = true,
  ...props
}: FormInputProps<TFormValues>): JSX.Element => {
  return (
    <div className={outerDivClassName}>
      <div className={innerDivClassName}>
        <label htmlFor={name} className="text-xs">{label}{props.required && '*'}</label>
        <Input
          name={name}
          label={label}
          className={inputClassName}
          { ...props }
          { ...(register && register(name)) }
        />
      </div>
      { isErrorMessageDisplayed && <ErrorMessage
          errors={errors}
          name={name as any}
          render={({ message }) => (
            <p className="text-xs text-deya-red-500">
              {message}
            </p>
          )}
        /> }
    </div>
  );
}

export default FormInput;

There's certainly a lot to parse from FormInputProps! Let's take it one step at a time.

The fields below are fairly simple and self-explanatory. We'll keep the discussion on the other parts.

export type FormInputProps = {
  // className props for styling different parts of the FormInput
  outerDivClassName?: string;
  innerDivClassName?: string;
  inputClassName?: string;

  // use cautiously, in cases where we don't want to display the error message, such as if you want to display
  // all error messages in a central area in your form, or if there are no errors possible
  // e.g. a checkbox where false and true are both valid
  isErrorMessageDisplayed?: boolean;
} & Omit<InputProps, 'name'>; // intersection with InputProps EXCEPT name

Some of our props are going to depend on what our form actually looks like; hence, we need to pass in a form values generic type. This type TFormValues also must inherit from the type FieldValues to be compatible with the register prop later on.

export type FormInputProps<TFormValues extends FieldValues> = {
  // ...
} & Omit<InputProps, 'name'>;

// FieldValues type for reference
type FieldValues = {
  [x: string]: any;
}

Case in point, our name prop, which curiously isn't of type String. If you're familiar with RHF, you might be familiar with syntax for getting values like root.arrayField.[0].fieldName or the more readable root.employees.[0].first_name. Similarly, our name must represent the exact path to the field, given TFormValues.

export type FormInputProps<TFormValues extends FieldValues> = {
  name: Path<TFormValues>;
  // ...
} & Omit<InputProps, 'name'>;

Finally, we have the register prop to register our input to a form, and our errors prop.

export type FormInputProps<TFormValues extends FieldValues> = {
  // ...
  register?: UseFormRegister<TFormValues>;
  errors?: Partial<DeepMap<TFormValues, FieldError>>;
  // ...
} & Omit<InputProps, 'name'>;

DeepMap is a type under RHF that recursively maps the keys of an object (or form) to some value. This means that it would change your hypothetical form this way:

const formValues = {
  user: {
    name: '',
    address: {
      street: '',
      city: ''
    }
  }
};

const errors = {
  user: {
    name: SomeFieldErrorOrNothing,
    address: {
      street: { message: "Street is required" },
      city: SomeFieldErrorOrNothing,
    }
  }
};

But as you may have noticed from that snippet, we won't always have field errors for every part of the form; hopefully, we won't have errors at all! This is where Partial comes in, which trims things down to only what's necessary:

const errors = {
  user: {
    address: {
      street: { message: "Street is required" },
    }
  }
};

One notable difference between this guide and its predecessor is that we forego the usage of a rules property that would be passed to our FormInput. This is because we will make use of an RHF resolver on the form level instead.

...and that's it! We now have a universal <FormInput> component that we can use anywhere within our app.

Prerequisites for the form

Before we move on to creating a form and tying all of our moving parts together, we have some boxes to tick off:

Creating some types

// src/types.ts

export type EmployeeForm = {
  first_name: String;
  employee_number: Number;
}

export type EmployeeCreateRequest = {
  employee: EmployeeForm;
}

export const defaultEmployeeFormValues = {
  first_name: '',
  employee_number: 0,
}

Creating a hook to mock db operations

// src/hooks.ts

import { useMutation } from "@tanstack/react-query"
import { EmployeeCreateRequest } from "./types"

const createEmployee = async(req: EmployeeCreateRequest) => {
  // normally you'd want to make an axios request to your backend API here
  console.log(req);
}

export const useCreateEmployee = () => {
  return useMutation({
    mutationFn: (req: EmployeeCreateRequest) => createEmployee(req)
  })
}

Writing validation

// src/validation.ts

import * as z from "zod";

export const createEmployeeSchema = z.object({
  first_name: z.string().min(1).max(20),
  employee_number: z.coerce.number().refine(val => Number(val) >= 0 , 'The number must not be less than 0'),
});

Putting everything together

With all that being done, we can finally write our form:

// src/App.tsx

import { DeepMap, FieldError, useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

import { createEmployeeSchema } from "./validation";
import { EmployeeCreateRequest, EmployeeForm, defaultEmployeeFormValues } from "./types";
import { useCreateEmployee } from "./hooks";
import FormInput from "./components/FormInput";

export default function App() {

  // you can use variable names like `register` as-is, but this is more explicit
  // and will come in handy whenever you need more than 1 form in your component
  const {
    register: createEmployeeFormRegister,
    handleSubmit: createEmployeeFormHandleSubmit,
    getValues: createEmployeeFormGetValues,
    formState: createEmployeeFormState,
  } = useForm<EmployeeForm>({
    defaultValues: defaultEmployeeFormValues,
    mode: 'onBlur',
    resolver: zodResolver(createEmployeeSchema)
  });

  // we must ensure that errors are coerced to the right type
  const { errors: createEmployeeFormErrors } = createEmployeeFormState as {
    errors: Partial<DeepMap<EmployeeForm, FieldError>>
  };

  // simulate a request to the DB on submit
  const createEmployeeMutation = useCreateEmployee();
  const onCreateEmployeeFormSubmit = createEmployeeFormHandleSubmit(() => {
    const payload: EmployeeCreateRequest = { employee: createEmployeeFormGetValues() }
    createEmployeeMutation.mutate(payload);
  })

  return (
    <div className="w-96 p-4">
      <h1 className="text-indigo-500 mb-4">Form with basic inputs</h1>

      <form onSubmit={onCreateEmployeeFormSubmit} className="flex flex-col gap-2">
        <FormInput<EmployeeForm> // don't forget to pass in TFormValues to your FormInput!
          id="first_name"
          name="first_name" // note that here you might pass something like employees.[0].first_name as well
          label="First Name"
          register={createEmployeeFormRegister}
          errors={createEmployeeFormErrors}
          required={true}
        />

        <FormInput<EmployeeForm>
          type="number"
          id="employee_number"
          name="employee_number"
          label="Employee Number"
          register={createEmployeeFormRegister}
          errors={createEmployeeFormErrors}
          required={true}
        />

        <button type="submit" className="rounded-md text-white bg-blue-500 hover:bg-blue-600 p-2">Submit</button>
      </form>
    </div>
  )
}

That should be it! You can expect error messages to show right underneath the form inputs. Otherwise, if your form is valid, submitting should log its contents to the console.

Cheers!

References

Keionne Derousselle's blog post was the inspiration for this guide, and a lot of what I say here is taken directly from what I learned from their post. None of this would have been possible without them--literally, I couldn't find any other guides that were helpful to me at the time--if you're here looking for answers to a problem you have, you might have come across their post already. If you haven't, then do give the post a read!
Official documentation for react-hook-form

Setting up private routes with react router v6

Kirby Aguilar — Thu, 26 Sep 2024 12:39:26 +0000

When I was tasked to lead my previous company's Rails+React app development, I had zero real React experience. One month into the development process, I had to put most of our routes behind a wall of auth.

I encountered a few snags:

None of the solutions I found online felt simple enough, nothing I could do in 5 minutes. At my level at the time, it seemed like every guide needed complex hooks or React knowledge that I simply didn't have yet.
Our project was using the newer Router Provider syntax. Most of the guides I found were using the older JSX syntax for routes
Our project's auth was being done using devise and devise-jwt. Ideally, I would have wanted a quick and dirty implementation of react-router private routes that throws the responsibility of actual auth all to the backend, but I couldn't find that at the time.

This problem has been long solved for our project, but I wanted to share the solution we landed on.

Skipping to the end, for impatient readers who know what they're doing

If you don't care for the details, you can skip to the end via the GitHub repository. You'll want to be looking at router.tsx, hooks/useAuth.ts and components/PrivateRoute.tsx.

The goal

If you do care about the details, then you'll want to know that we want to achieve the following:

"Is this route private?" needs to be something we can configure per route
"Is this route private?" also needs to be something we can configure per layout. i.e. if my route's parent is private, I won't have to set the child route to private.
Authentication needs to happen within the app's backend API.

Project Setup

This section covers how to create this project through npm and Vite.

$ npm create vite@latest react-router-protected-routes -- --template react-ts
$ cd react-router-protected-routes && npm install
$ npm install react-router-dom

# remove boilerplate files that we do not need 
$ cd src && rm -rf assets/ App.tsx App.css index.css && cd ..

Let's make a couple of pages:

// src/pages/Login.tsx
export default function Login() {
  return (
    <>
      <h1>Login page</h1>
    </>
  );
}

// src/pages/Protected.tsx
export default function Protected() {
  return (
    <h1>This should only be visible if you are logged in</h1>
  );
}

1. Creating our router and setting up `main.tsx`

We elect to use createBrowserRouter as per react-router's official recommendation in their docs.

// src/router.tsx
import { createBrowserRouter } from "react-router-dom";

import Login from "./pages/Login";
import Protected from "./pages/Protected";

/**
 * Notice how "main" routes and auth routes (like login or signup) are separated below.
 * This mimics how a real project may be set up: these two sets of routes would likely
 * have a different layout file, main routes would be protected while auth routes would not, etc
 */
const router = createBrowserRouter([
  // main routes
  {
    path: '/',
    element: <Protected />
  },

  // auth routes
  {
    children: [
      { path: 'login', element: <Login /> },
    ],
  },
])
export default router;

We then edit main.tsx such that it makes use of the router we just created:

// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { RouterProvider } from 'react-router-dom'

import router from './router'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>,
)

At this point, you can $ npm run dev to ensure that navigation is working. We haven't implemented private routes yet, so you should be able to see both / and /login.

2. The `useAuth` custom hook

Before we can create a PrivateRoute component, we need to write the custom hook that we'll use within the component to see a user's authentication status.

As shown below, if you're using this within your app then you'd be calling the backend API within the try block to check there whether the user is authenticated or not.

// src/hooks/useAuth.ts
import { useEffect, useState } from "react";

export const useAuth = () => {
  const [isAuthenticated, setIsAuthenticated] = useState<boolean | null>(null);

  useEffect(() => {
    const fetchData = async () => {      
      try {
        // Normally here we'd send a request to a protected route of the backend API of the app.
        // whether or not the user is authenticated depends on the result of the request
        // await axios.get("/api/arbitrary");

        // For our purposes, we'll simulate a 250ms delay in place of the API call
        await new Promise(resolve => setTimeout(resolve, 250));

        // Set this to true for testing
        const simulateFailure = false;
        if (simulateFailure) throw new Error("Failed to authenticate");

        setIsAuthenticated(true)
      } catch (error) {
        console.error("Error fetching data:", error);
        setIsAuthenticated(false);
      }
    };

    fetchData();
  }, []);

  return isAuthenticated;
};

Some readers might have noticed something strange. See the line below:

const [isAuthenticated, setIsAuthenticated] = useState<boolean | null>(null);

Why is it that isAuthenticated is allowed to be null?

This is because there are three possible states in determining a user's authentication status:

The user is authenticated.
The user is not authenticated.
We don't know yet--likely because we're still waiting for a response from the backend. This "loading" state is what we represent with null, as you'll see from our PrivateRoute component.

3. The `PrivateRoute` component

We pass in a component to the PrivateRoute. While checking for the authentication status, we return a loading state (you could use a spinner or something similar here instead).

Afterwards, we return the passed in component if authentication was successful, and a redirect to the non-private route /login if not.

// src/components/PrivateRoute.tsx
import { Navigate } from "react-router-dom";
import { useAuth } from "../hooks/useAuth";

type PrivateRouteProps = {
  component: React.FC;
}

const PrivateRoute: React.FC<PrivateRouteProps> = ({ component: Component }) => {
  const isAuthenticated = useAuth();
  if (isAuthenticated === null) return <div>Loading...</div>;
  return isAuthenticated ? <Component /> : <Navigate to="/login" />;
};

export default PrivateRoute;

To make use of private routes, simply pass it in as a route's element in router.tsx like so:

// src/router.tsx
import PrivateRoute from "./components/PrivateRoute";
// ...
const router = createBrowserRouter([
  // main routes
  {
    path: '/',
    element: <PrivateRoute component={Protected} />
  },
// and so on

And that's it! You should now be able to set routes as private. If you want to set a whole family of routes as private, simply provide PrivateRoute with a layout file that makes use of an <Outlet> and the children should become private as well.

An important caveat

This all happened to be a quick and dirty solution that we were fine using a bit long-term at my previous company, but it's not perfect. You may have noticed that useAuth calls the backend API to check for authentication every single time a component is rendered.

While it's outside the scope of this guide, you can counteract this by caching, using react's context API, or through a state management library.

References

While I wasn't able to find a perfect reference for myself before (hence this article), I was still able to find other helpful sources that were instrumental in figuring out what to do. If this tutorial wasn't the right one for you, maybe I can at least lead you to the right place:

Forem: Kirby Aguilar

Deploying a Rails 7 + React app to AWS via Dokku

Enter Dokku 🐋

What we want to achieve in this guide

The app

Details that you should know about the app

High level infrastructure

Step-by-step infrastructure setup

Create a VPC

Create an RDS Postgres database

Create/edit security groups to allow communication between the RDS db and EC2 instances

Store the necessary secrets in AWS secrets manager

Create an IAM role to access secrets

Create a security group for the EC2 instances

Create a launch template

Create an auto scaling group

Enabling HTTPS (optional)

EC2 launch script and dokku settings

Recommendations for the future of this guide

Final words

References

Reusable form inputs with React Hook Form and TypeScript

What we overlooked

What we want to achieve

Skipping to the end

Other tools we'll work with

Project setup

The <Input> Component

<FormInput> and the types that come with it

Prerequisites for the form

Setting up private routes with react router v6

Skipping to the end, for impatient readers who know what they're doing

The goal

Project Setup

1. Creating our router and setting up main.tsx

2. The useAuth custom hook

3. The PrivateRoute component

An important caveat

References

The `<Input>` Component

`<FormInput>` and the types that come with it

1. Creating our router and setting up `main.tsx`

2. The `useAuth` custom hook

3. The `PrivateRoute` component