In this article, I will show you a step-by-step guide on deploying a Next.js app (SSR mode) to Fly.io. We will deploy a MySQL database to Fly.io as well. Although you have the option to choose other databases, I will be using MySQL in this case as I am migrating away from PlanetScale, which is a MySQL database under the hood.

## What does the result look like?

In the end, your application architecture will be:

- Next.js app (SSR mode) running on a VM (via Docker container) in Fly.io.
- MySQL database also running on Fly.io, with an attached persistent volume, and residing in the same private network as the Next.js app.
- We will use Cloudflare as a DNS and handle non-www to www redirection (i.e., redirect `crispyscript.com` to `www.crispyscript.com`).

![Before and after, architecture](https://res.cloudinary.com/pob/image/upload/v1710783692/next-blog/prod/k0ignltt34zpa1gwcgxw.png)

## Step 1: [MySQL] Initialize Fly.io setup for MySQL

For reference, you can consult the [documentation](https://fly.io/docs/app-guides/mysql-on-fly).

1.  Begin by creating a new directory. This can be nested within the Next.js project's directory or in another location on your computer.

    ```bash
    mkdir my-mysql
    cd my-mysql
    ```

2.  Initialize the Fly.io setup.

    ```bash
    fly launch --no-deploy --image mysql:8
    ```

3.  Edit the `fly.toml` file generated by `fly launch`:

    - Remove the entire `[http_service]` block.
    - Add `MYSQL_DATABASE` and `MYSQL_USER` into the `[env]` block.
    - Add `[processes]` and `[mounts]` blocks.

    The final `fly.toml` file should resemble the following (note that I've chosen the "shared-cpu-1x" machine with "1gb" memory):

    ```toml
    app = 'my-mysql'
    primary_region = 'sin'

    [build]
      image = 'mysql:8'

    [[vm]]
      size = 'shared-cpu-1x'
      memory = "1gb"

    [processes]
      app = """--datadir /data/mysql \
        --default-authentication-plugin mysql_native_password"""

    # We will create `mysqldata` with `fly volumes` later
    [mounts]
      source = "mysqldata"
      destination = "/data"

    # For non-sensitive env variables only!
    # The other sensitive env variables(including `MYSQL_PASSWORD`) are in `fly secrets`
    [env]
      MYSQL_DATABASE = "blog"
      MYSQL_USER = "any_username"
    ```

## Step 2 (Optional): [MySQL] Set up auto start/stop feature

_Edited: I found that sometimes the auto-start feature does not work properly. It causes an unexpected error when trying to connect to MySQL via `*.flycast` address. My recommendation is to skip this step until the issue is fixed._

---

_The original content:_

For reference, you can refer to [Q&A 1](https://community.fly.io/t/automatically-starting-stopping-apps-v2-instances/12342/30) | [Q&A 2](https://community.fly.io/t/access-fly-io-database-from-retool/5582/3) | [The Documentation](https://fly.io/docs/networking/private-networking/#flycast-private-load-balancing).

This step is optional.

You can configure Fly.io to automatically stop a MySQL container when there is no traffic to save costs.

1. Add `[[services]]` and `[[services.ports]]` blocks to `fly.toml` file.

   ```toml
   # Add this to the end of `fly.toml` file in "Step 1"

   [[services]]
     internal_port = 3306
     protocol = "tcp"
     processes = ["app"]
     auto_stop_machines = true
     auto_start_machines = true
     min_machines_running = 0

     [[services.ports]]
       handlers = []
       port = 3306
   ```

2. Complete "Step 3" to "Step 5" to deploy MySQL for the first time. Then, return here and proceed to "3." below.
3. While still in the `my-mysql` directory, execute this command:

   ```bash
   fly ips allocate-v6 --private
   ```

   The result should resemble this when you run the `fly ips list` command:

   ```
   VERSION  IP                  TYPE      REGION    CREATED AT
   v6       fdaa:0:22b7:0:1::3  private   global    just now
   ```

Now, for the remainder of this article, replace any of `my-mysql.internal` with `my-mysql.flycast`.

## Step 3: [MySQL] Create a volume

For reference, consult the [documentation](https://fly.io/docs/app-guides/mysql-on-fly/#configure-the-app).

In the `my-mysql` directory, run the following command to create the `mysqldata` volume. I've opted for 1GB of disk space, as my website is relatively simple.

```bash
# Create a volume named "mysqldata" within our app "my-mysql"
fly volumes create mysqldata --size 1 # gb
```

![The volume result in Fly.io dashboard](https://res.cloudinary.com/pob/image/upload/v1710788153/next-blog/prod/fzw2dxenlr435aet77ga.png)

## Step 4: [MySQL] Add sensitive env variables into `fly secrets`

For reference, refer to the [documentation](https://fly.io/docs/app-guides/mysql-on-fly/#configure-the-app).

The MySQL container requires two sensitive environment variables: `MYSQL_PASSWORD` and `MYSQL_ROOT_PASSWORD`. Place them into `fly secrets`.

```bash
# Set secrets:
# MYSQL_PASSWORD      - password set for user $MYSQL_USER (which we already set the value in "Step 1")
# MYSQL_ROOT_PASSWORD - password set for user "root"
fly secrets set MYSQL_PASSWORD=your_password MYSQL_ROOT_PASSWORD=your_root_password
```

You can check the result by:

```bash
fly secrets list
```

## Step 5: [MySQL] Deploy MySQL to Fly.io

Finally, run this command in the `my-mysql` directory:

```bash
fly deploy
```

![MySQL is successfully deployed as shown in Fly.io dashboard](https://res.cloudinary.com/pob/image/upload/v1710795948/next-blog/prod/hlkxryct5vvt94rzrylp.png)

**Caveat:** Upon the first deployment, if any mistakes were made or if the username/password weren't set properly, broken data may persist in the volume, and subsequent deployments may still read this broken data. To fix this, you can remove the `mysqldata` volume and recreate it from scratch.

## Step 6 (Optional): [PlanetScale Migration] Migrate data from PlanetScale to MySQL (in Fly.io)

This step is optional.

For people who want to migrate the existing data in PlanetScale to Fly.io, the following steps are what you're looking for.

1. Connect your local machine to MySQL in Fly.io. You'll need to install WireGuard and create a Fly.io tunnel. Refer to the [documentation](https://fly.io/docs/networking/private-networking/#step-by-step).

   1. Install WireGuard
   2. In the `my-mysql` directory, run:

      ```bash
      fly wireguard create
      ```

   3. Follow the instructions and save the output as a file, `basic.conf`, for instance:

      ```
      !!!! WARNING: Output includes private key. Private keys cannot be recovered !!!!
      !!!! after creating the peer; if you lose the key, you’ll need to remove    !!!!
      !!!! and re-add the peering connection.                                     !!!!
      ? Filename to store WireGuard configuration in, or 'stdout':  basic.conf
      Wrote WireGuard configuration to 'basic.conf'; load in your WireGuard client
      ```

      Note: don't push this file, `basic.conf`, to GitHub!

   4. Run the WireGuard app. Click the `Import tunnel(s) from file` button. Select your configuration file. After successfully imported, `Activate` it.
   5. Now, you should be able to connect to `my-mysql.internal:3306`, using your `MYSQL_USER`, `MYSQL_PASSWORD`, and `MYSQL_DATABASE`. Try it with any MySQL clients, e.g. TablePlus, cli tools.

2. Back up all schemas and data from PlanetScale. Refer to the [documentation](https://planetscale.com/docs/concepts/hobby-plan-deprecation-faq#how-do-i-migrate-off-of-planetscale-).

   ```bash
   pscale db dump <DATABASE_NAME> <BRANCH_NAME>
   ```

   For example, if your database name in PlanetScale is `planetblog`:

   ```bash
   pscale db dump planetblog main
   ```

   You will receive a directory name similar to `pscale_dump_planetblog_main_20240305_144231`. Within the directory, you'll find a `planetblog.TableName-schema.sql` file containing the schema for the database, as well as one or more files with names like `planetblog.TableName.00001.sql`, which contain the data. Note: Do not push the `pscale_dump_*` directory to GitHub!

3. Restore the backup to MySQL in Fly.io.

   1. Install `mydumper`

      ```bash
      brew install mydumper
      ```

   2. Create a `db.ini` file to provide all necessary information on how to connect to Fly.io MySQL from the local machine. Note: Do not push this file to GitHub!

      ```
      [myloader]
      host = my-mysql.internal
      user = any_username
      password = your_password
      database = blog
      port = 3306
      ```

   3. Execute this command:
      ```bash
      myloader --defaults-file db.ini --directory pscale_dump_planetblog_main_20240305_144231/
      ```

Now, all data between PlanetScale and Fly.io MySQL should be identical.

## Step 7: [Next.js] Initialize Fly.io setup and set `NEXT_PUBLIC_*` env variables

For reference, consult the [documentation](https://fly.io/docs/js/frameworks/nextjs/).

After signing in to Fly.io and installing their CLI tool (`flyctl`), navigate to the directory containing your Next.js app. Run `fly launch` to initialize the Fly.io setup. For example, if the Next.js project is in the `my-next-app` directory, execute:

```bash
cd my-next-app
fly launch
```

You should get `Dockerfile` and `fly.toml` files. Next, add all your `NEXT_PUBLIC_*` env variables into the `Dockerfile` below the `FROM base as build` line.

In the end, your `Dockerfile` should resemble this:

```
ARG NODE_VERSION=21.6.2

FROM node:${NODE_VERSION}-slim as base
LABEL fly_launch_runtime="Next.js/Prisma"
WORKDIR /app
ENV NODE_ENV="production"
ARG PNPM_VERSION=8.15.4
RUN npm install -g pnpm@$PNPM_VERSION

FROM base as build

# ----- All `NEXT_PUBLIC_*` env variables go here -----
ARG NEXT_PUBLIC_WEB_URL="https://crispyscript.com"
# -----------------------------------------------------

RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential node-gyp openssl pkg-config python-is-python3
COPY --link package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod=false
COPY --link prisma .
RUN npx prisma generate
COPY --link . .
RUN pnpm run build
RUN pnpm prune --prod

FROM base
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y openssl && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives
COPY --from=build /app /app
EXPOSE 3000
CMD [ "pnpm", "run", "start" ]
```

> **Tip:** If you plan to connect your Next.js app with PlanetScale later, you need to `apt-get install ca-certificates` since PlanetScale requires a SSL connection. Edit the last section in `Dockerfile`:
>
> ```
> ... (no change)
>
> FROM base
> RUN apt-get update -qq && \
>     # ------ Add ca-certificates to the next line ------
>     apt-get install --no-install-recommends -y openssl ca-certificates && \
>     rm -rf /var/lib/apt/lists /var/cache/apt/archives
> COPY --from=build /app /app
>
> ... (no change)
> ```

Additionally, the `fly.toml` file should resemble this (note that I've selected the "shared-cpu-1x" machine with "512mb" of memory):

```toml
app = 'my-next-app'
primary_region = 'sin'

[build]

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0
  processes = ['app']

[[vm]]
  size = 'shared-cpu-1x'
  memory = "512mb"
```

## Step 8: [Next.js] Set up remaining env variables

For reference, refer to the [documentation](https://fly.io/docs/reference/secrets/).

There are two groups of environment variables for the Next.js app:

1. **Group 1**: `NEXT_PUBLIC_*` variables - Put them into the `Dockerfile` as mentioned in "Step 7" above.
2. **Group 2**: All runtime variables including sensitive variables, e.g., `DATABASE_URL`, `NEXTAUTH_URL`, `CLOUDINARY_API_KEY` - Place them into `fly secrets` in this step.

In the `my-next-app` directory, execute this command to place all "Group 2" variables into `fly secrets` one by one:

```bash
fly secrets set NEXTAUTH_URL=https://crispyscript.com
fly secrets set CLOUDINARY_API_KEY=xxxxx
...
```

For the `DATABASE_URL` variable, use a connection string following this pattern: `mysql://{MYSQL_USER}:{MYSQL_PASSWORD}@my-mysql.internal/{MYSQL_DATABASE}`. Prisma will use this variable to connect to MySQL. If you use another ORM, please adjust accordingly.

```bash
fly secrets set DATABASE_URL='mysql://any_username:your_password@my-mysql.internal/blog'
```

**Note:**

- If you've set up Flycast in "Step 2 (Optional)", use `my-mysql.flycast` instead of `my-mysql.internal` for `DATABASE_URL`.
- We aren't utilizing SSL connection between our Next.js app and MySQL since they are within the same private network.

To list all variable names, which have been set so far:

```bash
fly secrets list
```

![Fly.io dashboard -> "Secrets" menu](https://res.cloudinary.com/pob/image/upload/v1710800338/next-blog/prod/uwhzsj0qfxz9izh921tw.png)

## Step 9: [Next.js] Install `sharp`

Since we'll be self-hosting the Next.js app on our VM instead of utilizing the Vercel platform, we need the `sharp` package for image optimization feature.

```bash
pnpm add sharp
```

## Step 10: [Next.js] Deploy the Next.js app to Fly.io

In the `my-next-app` directory, simply run:

```bash
fly deploy
```

You'll receive the deployed URL (e.g., `https://my-next-app.fly.dev`) as a result.

**Note:** You can utilize `fly logs` to debug or access the tailing log of the Next.js app.

## Step 11: [DNS] Set up Cloudflare to redirect non-www to www URL

If you're not already using Cloudflare as your DNS provider, go through their documentation to set it up. For example, I set up Cloudflare as a DNS provider with a Namecheap domain by following this [documentation](https://www.namecheap.com/support/knowledgebase/article.aspx/9607/2210/how-to-set-up-dns-records-for-your-domain-in-a-cloudflare-account/).

After setting up Cloudflare as your DNS provider, there are a few more steps:

1. In the `my-next-app` directory, execute `fly certs add` for both the www and non-www URLs. Refer to the [documentation](https://fly.io/docs/networking/custom-domain/) for guidance.

   ```bash
   fly certs add crispyscript.com
   fly certs add www.crispyscript.com
   ```

   !["Certificates" menu in Fly.io dashboard](https://res.cloudinary.com/pob/image/upload/v1710827767/next-blog/prod/ws7eivoa6dcjga8obmv4.png)

2. Navigate to the Cloudflare dashboard -> "DNS" menu -> "Records" menu.
3. Add the following 2 records:

   ```
   Type      Name      Content                 Proxy status      TTL
   CNAME     @         my-next-app.fly.dev     Proxied           Auto
   CNAME     www       my-next-app.fly.dev     Proxied           Auto
   ```

   !["Records" menu in Cloudflare dashboard](https://res.cloudinary.com/pob/image/upload/v1710828105/next-blog/prod/lzzmkyzdpxg6tcqqtq3g.png)

4. Go to the Cloudflare dashboard -> "SSL/TLS" menu -> "Overview" menu.
5. Select "Full - Encrypts end-to-end, using a self-signed certificate on the server." This step is crucial. The default option "Flexible" causes a `520` error on my website. Refer to this [solution](https://blog.majsky.cz/using-flyio-custom-domain-with-cloudflare-as-proxy/).

   !["SSL/TLS" menu in Cloudflare dashboard](https://res.cloudinary.com/pob/image/upload/v1710828424/next-blog/prod/uqsaiavqxggrjdgoywzu.png)

6. Navigate to the Cloudflare dashboard -> "Rules" menu -> "Page Rules" menu.
7. Create a page rule to redirect non-www to www:

   ```
   URL:
   crispyscript.com/*

   Then the settings are:
   Forwarding URL - 301 Permanent Redirect

   Destination URL:
   https://www.crispyscript.com/$1
   ```

   !["Page Rules" menu in Cloudflare dashboard](https://res.cloudinary.com/pob/image/upload/v1710828652/next-blog/prod/x3u42fe5k3yeyfitdyph.png)

## Final Result

After going through all steps, the final result would be:

1. All of these URLs:

   ```
   http://crispyscript.com
   https://crispyscript.com
   http://www.crispyscript.com
   https://www.crispyscript.com
   ```

   should be redirected to:

   ```
   https://www.crispyscript.com
   ```

2. There will be two apps on Fly.io: the Next.js app (named `my-next-app`) and MySQL (named `my-mysql`). You can check their status on the Fly.io dashboard.

   ![Two apps are shown in Fly.io dashboard](https://res.cloudinary.com/pob/image/upload/v1710829249/next-blog/prod/tjudhgmvkbjtp8qhhw8y.png)

## Next Steps

You can also set up a custom email address (e.g., `your_name@crispyscript.com`) and integrate it with your free Gmail account. This enables you to "send" and "receive" emails on behalf of the custom email address. Follow this [instruction](https://gist.github.com/irazasyed/a5ca450f1b1b8a01e092b74866e9b2f1) if you're interested.


In other words: How to deploy a Next.js app (SSR mode) with MySQL as a database, to Fly.io

Migrate Next.js app away from "Vercel + PlanetScale" to "Fly.io"

In Javascript, I normally use `===` (triple equals) 99% of the time. However, I've found that one of the great remaining use cases for `==` (double equals) is when I want to check whether the value is `null` or `undefined`.

```js
// A variable that can be a number, `null` or `undefined`
let myAge = 42
myAge == null // false
myAge = null
myAge == null // true
myAge = undefined
myAge == null // true

// The triple equals version is more verbose
myAge = 42
myAge === null || myAge === undefined // false
myAge = null
myAge === null || myAge === undefined // true
myAge = undefined
myAge === null || myAge === undefined // true
```

I also use it a lot in TypeScript when the value is nullable and optional.

```ts
// The `age` argument is nullable and also optional
function isAdult(age?: number | null) {
  if(age == null) {
    throw new Error('You need to provide your age')
  }
  return age >= 18
}
```

Happy coding!


JS Tip: `== null` is my favorite use case of double equals

## Situation

Imagine that you want to render different components based on the `fetchStatus` prop. Its possible values are `loading`, `success`, and `error`.

```tsx
function BlogContent({
  fetchStatus,
  data,
}: {
  fetchStatus: 'loading' | 'success' | 'error'
  data: string | null
}) {
  // Conditional rendering here
  // ...
}
```

## First Attempt

Nested ternary! I see this approach being used in too many codebases. I think this approach should be avoided when there are more than 2 possible rendering branches, as it's not good for readability in my opinion.

```tsx
function BlogContent({
  fetchStatus,
  data,
}: {
  fetchStatus: 'loading' | 'success' | 'error'
  data: string | null
}) {
  // Nested ternary. This should be avoided.
  return (
    <div>
      {fetchStatus === 'loading' ? (
        <span>Loading...</span>
      ) : fetchStatus === 'success' ? (
        <p>{data}</p>
      ) : (
        <span>There was an error</span>
      )}
    </div>
  )
}
```

## A Better Approach: Extract the Condition from JSX

A better approach is to extract the condition from JSX and store the result in a variable, e.g. `content` in this case.

```tsx
function BlogContent({
  fetchStatus,
  data,
}: {
  fetchStatus: 'loading' | 'success' | 'error'
  data: string | null
}) {
  // Extract the condition from JSX and store the result in "content"
  let content
  if (fetchStatus === 'loading') {
    content = <span>Loading...</span>
  } else if (fetchStatus === 'success') {
    content = <p>{data}</p>
  } else {
    content = <span>There was an error</span>
  }
  // Use "content" variable in JSX
  return <div>{content}</div>
}
```

This approach is good enough. However, what if I want to put the full if-else condition right inside the JSX? Since it allows me to easily scan the code from top to bottom without having to jump around the lines.

## Making Use of switch-case Inside JSX

Because we can only put an expression inside JSX, we need a little trick to overcome this limitation: **IIFE to the rescue!**

```tsx
function BlogContent({
  fetchStatus,
  data,
}: {
  fetchStatus: 'loading' | 'success' | 'error'
  data: string | null
}) {
  // Using IIFE to put the condition inside JSX
  return (
    <div>
      {(() => {
        switch (fetchStatus) {
          case 'loading':
            return <span>Loading...</span>
          case 'success':
            return <p>{data}</p>
          case 'error':
            return <span>There was an error</span>
          default:
            throw new Error('There is an unhandled case')
        }
      })()}
    </div>
  )
}
```

That's a little tip for today. Happy coding everyone!


When you need to conditionally render a component based on multiple conditions

React Tip: Making use of switch-case in JSX

## What is "Prop Drilling"

Prop drilling is passing props through intermediary components to reach the target component, which is the actual consumer. Consider the code below:

```js
function App() {
  return <Parent />
}

function Parent() {
  const [count, setCount] = useState(0)
  return <Child count={count} />
}

function Child({ count }) {
  return <GrandChild count={count} />
}

function GrandChild({ count }) {
  return <div>Count is {count}</div>
}
```

![what is prop drilling](https://res.cloudinary.com/pob/image/upload/v1680201210/next-blog/prod/sv6gsmqavq35o4aesggz.png)

In this example, `count` is passed through `<Child/>` before it reaches `<GrandChild/>`. The `<Child/>` component does not actually use the `count` prop but simply forwards it to the `<GrandChild/>`. This is "Prop Drilling".

## Solutions

### Option 1: Do nothing

Prop drilling is not always a problem. If we have only a few levels of components, it is simpler and more explicit to pass the props down. This also makes it clear what the inputs of each component are, as if they were arguments of a function.

### Option 2: Component composition

We can directly pass the prop to the target component by making use of `children` prop.

```js
function App() {
  return <Parent />
}

function Parent() {
  const [count, setCount] = useState(0)
  return (
    // We don't need to pass `count` prop to <Child/> anymore
    <Child>
      {/* Directly pass `count` to <GrandChild/> */}
      <GrandChild count={count} />
    </Child>
  )
}

// Make use of `children'
function Child({ children }) {
  return <>{children}</>
}

function GrandChild({ count }) {
  return <div>Count is {count}</div>
}
```

![component composition](https://res.cloudinary.com/pob/image/upload/v1680201241/next-blog/prod/xxnsdcvsvmu7lsphncej.png)

Note that in this case, `<GrandChild/>` does not accept any props from `<Child/>`.

But, what if we want to pass some props from `<Child/>` to `<GrandChild/>`? That's where option 3 comes in.

### Option 3: Render prop

By using this pattern, `<GrandChild/>` can accept different props from multiple parent components.

```js
function App() {
  return <Parent />
}

function Parent() {
  const [count, setCount] = useState(0)
  return (
    <Child
      // Render prop
      // <Child/> will pass `unit` to this function
      renderText={(unit) => {
        // - Directly pass `count` to <GrandChild/>
        // - Grab `unit` from the function arg and pass it to <GrandChild/> as well
        return <GrandChild count={count} unit={unit} />
      }}
    />
  )
}

function Child({ renderText }) {
  const [unit, setUnit] = useState('cat(s)')
  // Call the render prop by passing `unit` as an arg
  return <>{renderText(unit)}</>
}

function GrandChild({ count, unit }) {
  return (
    <div>
      Count is {count} {unit}
    </div>
  )
}
```

![render prop](https://res.cloudinary.com/pob/image/upload/v1680201268/next-blog/prod/gwykp4jwdqxqmb9f6lpw.png)

The Render Prop pattern may take some time to understand if you are not familiar with it.

### Option 4: Context

Using Context should be the last resort as it changes the way we pass props from explicit to implicit. This approach can be useful in certain situations, but it is important to consider the downsides of using Context and to explore alternative options before resorting to it.

```js
function App() {
  return (
    <Parent>
      <Child />
    </Parent>
  )
}

const CountContext = createContext(null)

function Parent({ children }) {
  const [count, setCount] = useState(0)
  return <CountContext.Provider value={count}>{children}</CountContext.Provider>
}

function Child() {
  // There is no prop explicitly passed to <GrandChild/>
  return <GrandChild />
}

function GrandChild() {
  // Implicitly receive `count` from Context instead of explicitly receive it from props
  const count = useContext(CountContext)
  return <div>Count is {count}</div>
}
```

![context](https://res.cloudinary.com/pob/image/upload/v1680201299/next-blog/prod/lswbslsuit6a9ismzzth.png)


React Context should not be the only option for resolving the issue of "prop drilling". You may want to consider these alternative approaches.

Prop Drilling issue: Explore these options before using useContext()

What might not be obvious when using `react-query` is that the "error" `status` is actually divided into two distinct states: "loading error" and "refetch error". In this article, we will take a closer look at these two error states and how to handle them correctly.

## The single "error" state in pre-`react-query` era

In the past, when we fetched data from a REST endpoint using `useEffect()`, we typically had only three states: "loading", "error", and "success". While state handling is simple, this `useEffect()` approach had its limitations, including the lack of caching and refetch capabilities.

![3 states when using useEffect](https://res.cloudinary.com/pob/image/upload/v1677429059/next-blog/prod/r8ul0cdrk6apudo1ga4l.png)

## In `react-query`, the single "error" `status` consists of two states

At first glance, if you use the previous mental model or look at the `status` provided by `useQuery()`, you might think that there is only one "error" state.

```js
const query = useQuery(...)
console.log(query.status) // 'loading' | 'error' | 'success'
```

This is incorrect. As `react-query` adds more features like `refetchOnWindowFocus`, it also increases the total number of possible states. For the purposes of this article, we will only focus on the "error" `status`.

As shown in the diagram below, the "error" `status` actually consists of two different states: "loading error" and "refetch error". This information is crucial to correctly design your UI. In some cases, we may handle both of them similarly and display the same UI. However, there are some scenarios that may cause unexpected UI states if we don't handle them separately.

![react-query has two different error states](https://res.cloudinary.com/pob/image/upload/v1677518662/next-blog/prod/quwhsq6jrbskzrpy9r8h.png)

## Scenario

Suppose we are building a website for users to send their love messages to Pokemons. The user journey is as follows:

1. A user navigates to the website.
2. Components are mounted, and `useQuery()` fetches a list of Pokemons through a REST endpoint.
3. The UI displays each Pokemon name in a card.
4. Each card can be expanded. When it's expanded, there is a textarea for sending a message.

https://res.cloudinary.com/pob/video/upload/v1677429216/next-blog/prod/y0tz5kdiheg5dk45sfkl.mp4

The happy path looks good. But, how can we handle unhappy paths? Let's explore two different approaches.

## Approach 1: Render elements based on `status` only

In this approach, we handle states by checking for `status` as we normally would. It works fine and covers the "error" `status`, except in one edge case. What if:

1. A user visits the website.
2. The first fetch for Pokemon list succeeds.
3. The user clicks on one of the "Expand" buttons.
4. A textarea shows up.
5. The user types something but does not submit yet.
6. The user pauses and goes to another browser window/tab.
7. The internet connection drops.
8. The user comes back, and `refetchOnWindowFocus` kicks in.
9. **Issue**: All content and the textarea disappeared. The user lost their in-progress message.

Let's see the code and the result.

```ts
function App() {
  const query = useQuery(
    ['pokemons'],
    async () => {
      const {
        data,
      }: {
        data: { results: { name: string; url: string }[] }
      } = await axios.get('https://pokeapi.co/api/v2/pokemon')
      return { pokemons: data.results }
    },
    { retry: 0 }
  )
  return (
    <div>
      <h1>Home Page</h1>
      {(() => {
        switch (query.status) {
          case 'loading':
            return <div>Status: Loading...</div>
          case 'error':
            return <div>Status: Error</div>
          case 'success':
            return query.data.pokemons.map((poke) => {
              return <Card key={poke.name} pokeName={poke.name} />
            })
        }
      })()}
    </div>
  )
}
```

https://res.cloudinary.com/pob/video/upload/v1677429241/next-blog/prod/kj8vuev4nng0jpe0weiu.mp4

Codesandbox: https://codesandbox.io/s/rq-error-1-24f9n2?file=/src/App.tsx

In the example above, I imitated an internet connection drop by blocking the request. You will see that a "refetch error" blows away the whole page since we treat it like an initial "loading error". What can we do to preserve the textarea even if there is a "refetch error"?

## Approach 2: Fix the issue in Approach 1 by handling "loading error" and "refetch error" separately

In Approach 1, we saw that relying solely on the `status` can cause issues when dealing with different error states. In this approach, we will instead handle each error state separately using the help of `isLoadingError` and `isRefetchError`.

```ts
function App() {
  // ...

  return (
    <div>
      <h1>Home Page</h1>
      {/* ------ Handle each error state differently ------ */}
      {(() => {
        if (query.status === 'loading') return <div>Status: Loading...</div>

        // "loading error": no data displayed
        if (query.isLoadingError) return <div>Status: {query.status}</div>

        // "refetch error": display data in the cache, don't tear down the page
        if (query.isRefetchError || query.status === 'success') {
          return query.data.pokemons.map((poke) => {
            return <Card key={poke.name} pokeName={poke.name} />
          })
        }
        
        throw new Error('Unhandled state!!!')
      })()}
      {/* -------------------------------------------------- */}
    </div>
  )
}
```

https://res.cloudinary.com/pob/video/upload/v1677429265/next-blog/prod/hd9xkjssdfsmrogmtvxt.mp4

Codesandbox: https://codesandbox.io/s/rq-error-2-92s446?file=/src/App.tsx

By handling "loading error" and "refetch error" state separately, we ensure that our users can continue writing their message even if they switch browser tabs and lose internet connectivity.

## Summary

`react-query` comes with their wonderful features like `refetchOnWindowFocus`. It's also important to understand that there will be more possible states created by these features. Although this article mainly focuses on "error" `status`, the other `status` actually consist of different states as well. This is mentioned in [the official documentation](https://tanstack.com/query/latest/docs/react/guides/queries#why-two-different-states).

> Background refetches and stale-while-revalidate logic make all combinations for `status` and `fetchStatus` possible. For example:
>
> - a query in "success" `status` will usually be in "idle" `fetchStatus`, but it could also be in "fetching" if a background refetch is happening.
> - a query that mounts and has no data will usually be in "loading" `status` and "fetching" `fetchStatus`, but it could also be "paused" if there is no network connection.
>
> So keep in mind that a query can be in loading state without actually fetching data. As a rule of thumb:
>
> - The `status` gives information about the data: Do we have any or not?
> - The `fetchStatus` gives information about the `queryFn`: Is it running or not?


The "error" status is actually divided into "loading error" state and "refetch error" state

In react-query, when you handle "error" status, you actually handle two different error states

NextAuth.js can be used either with or without a database. In this article, we will explain the case where no database is involved. Once you have a good understanding of the mechanism behind NextAuth.js, plugging in a database will not be much different.

## What happens when a user logs in

![log-in flow diagram](https://res.cloudinary.com/pob/image/upload/v1676051562/next-blog/prod/ggs5xdech5kplfpumfoo.png)

Note:
- There are 3 parties involved:
	1. Browser, a.k.a. a user, a.k.a. a client-side of Next.js
	2. Serverless, a.k.a. a server-side of Next.js
	3. Auth0, an OAuth provider
- Our Next.js code runs on `1.` and `2.`. So these 2 parties are our website. We can fully control both.
- On the other hand, `3.` can be any OAuth provider, such as GitHub or Google. This is an external website that we need to cooperate.

Step-by-step explanation:
1. A user (browser) clicks "Log in". The browser will make a request to our Next.js serverless. The URL destination depends on the OAuth provider, e.g. `api/auth/signin/auth0`.
2. The serverless responds with a redirect status code.
3. The browser then follows the redirection, navigate away from our website, and land on Auth0 website.
4. The user (who is using the browser) is asked to log in to Auth0. If success, Auth0 will respond with another redirection and also attach an access code for using in the next step. Moreover, Auth0 also set cookies to remember a session between the browser and Auth0. Note that this is not the session between the browser and the serverless.
5. The browser follows the redirection and navigate back to our website. The destination URL is something like `api/auth/callback/auth0?code=123`. It is sending the access code to the serverless.
6. The serverless does not immediately send a response back yet. It instead makes a request to Auth0, giving the access code in exchange for an access token.
7. Auth0 responds with the access token to the serverless.
8. After receiving the access token from Auth0, the serverless then sends a response back to the browser, set cookies, and remember the session between the browser and the serverless. Now the user is logged in successfully.

## What happens when the page calls API routes (after the user has logged in)

![calling api flow diagram](https://res.cloudinary.com/pob/image/upload/v1676051742/next-blog/prod/ykrrszdkdjz1x8y0lkzd.png)

Note:
- NextAuth's `useSession()` runs on the Next.js client-side (browser)
- NextAuth's `getServerSession()` runs on the Next.js server-side (serverless)
- If our website need to call an external API endpoint, e.g. `https://external-domain.com/api`, we may need to proxy it through our API routes (serverless). So, it would be:
	```
	Browser
	🡣 (cookies)
	Serverless, e.g. my-domain.com/api/proxy 
	Get an access token on the server side
	🡣 (access token)
	external-domain.com/api
	```


What happens when a user clicks "Log in"?

Understand NextAuth.js flow

## TLDR

```css
*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

body {
  /* colors */
  --text-color: #333333;
  --bg-color: #f1f5ef;
  --link-text-color: #0070f3;
  --button-text-color: white;
  --button-bg-color: #7c3aed;
  --button-hover-bg-color: #c4b5fd;

  /* line-height */
  --paragraph-line-height: 1.5;

  overflow-wrap: break-word;
  tab-size: 2;
  color: var(--text-color);
  background-color: var(--bg-color);
}

h1,
h2,
h3,
h4,
h5,
h6 {
  margin-block-end: 1rem;
}

p,
ul {
  line-height: var(--paragraph-line-height);
  margin-block-end: 1rem;
}

a {
  color: var(--link-text-color);
  text-decoration: none;
}
a:hover,
a:focus,
a:active {
  text-decoration: underline;
}

button {
  padding: 0.25rem 0.5rem;
  color: var(--button-text-color);
  background-color: var(--button-bg-color);
  border: none;
  border-radius: 0;
  cursor: pointer;
}
button:focus,
button:hover,
button:active {
  background-color: var(--button-hover-bg-color);
}

img {
  display: block;
  margin-inline: auto;
  max-width: 100%;
}
```

## Explanation

```css
*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}
```

- `box-sizing: border-box` is the most important one. It even should be browser's default.
- For margin and padding, I like to remove them all and start with zero space. Later, I will gradually add it to each tag.

---

```css
body {
  /* all possible colors in your website */
  --text-color: #333333;
  --bg-color: #f1f5ef;
  --link-text-color: #0070f3;
  --button-text-color: white;
  --button-bg-color: #7c3aed;
  --button-hover-bg-color: #c4b5fd;
  /* ... other colors */

  /* line-height */
  --paragraph-line-height: 1.5;

  overflow-wrap: break-word;
  tab-size: 2;
  color: var(--text-color);
  background-color: var(--bg-color);
}
```

- I think all possible colors in our website should be centralized in a single place. I use CSS variables to define all values here. These variables will be used across all css files.
- Optionally, you can centralize `line-height`, `z-index`, or spacing here as well.
- `overflow-wrap: break-word` to prevent a horizontal scroll when there is a long text, e.g. URL, and the screen size is small.
- `tab-size: 2` for display a tab character as 2 spaces. The tab character might be appeared in `textarea` and `pre` tags.

---

```css
h1,
h2,
h3,
h4,
h5,
h6 {
  margin-block-end: 1rem;
}

p,
ul,
ol {
  line-height: var(--paragraph-line-height);
  margin-block-end: 1rem;
}
```

- For `margin-block-end` (a.k.a. `margin-bottom`), I think `1rem` looks good for headings, paragraph, and list.
- However, for `line-height`, I think the browser's default only looks good on headings. It's too tight for others. So, I set it to `1.5` for paragraph and list.

---

```css
a {
  color: var(--link-text-color);
  text-decoration: none;
}
a:hover,
a:focus,
a:active {
  text-decoration: underline;
}
```

- I use my custom color for a normal-state anchor tag. This will also eliminate all browser's default colors for other states. In other words, all `:hover`, `:focus`, `:active`, `:visited` states will be the same `color` as a normal state.
- The `outline` when a user navigates by pressing a tab key, however, will not be replaced. It's still using the browser's default style.

---

```css
button {
  padding: 0.25rem 0.5rem;
  color: var(--button-text-color);
  background-color: var(--button-bg-color);
  border: none;
  border-radius: 0;
  cursor: pointer;
}
button:focus,
button:hover,
button:active {
  background-color: var(--button-hover-bg-color);
}
```

- I replace most of the browser's default style for `button` tag. This also makes our button style stays consistence across all browsers / OS.
- Similar to `a` tag, the `outline` is not replaced and still using the browser's default.

---

```css
img {
  display: block;
  margin-inline: auto;
  max-width: 100%;
}
```

- Horizontally center an image.
- In case the image's width is wider than its container, `max-width: 100%` will prevent overflow issue.

---


The bare minimum CSS reset that I always use to start with

My CSS reset with line-by-line explanation

## Part 1: Vite + React + Typescript

1. Initialize the project using `pnpm`
```bash
pnpm create vite
```
2. Follow the prompts, select `react` and `typescript` template
3. Start a dev server
```bash
pnpm run dev
```

## Part 2: Vitest + react-testing-library(i.e. RTL)

1. Install `vitest`, RTL and other necessary packages using `pnpm`
```bash
pnpm add -D vitest @testing-library/react @testing-library/user-event @testing-library/dom jsdom @testing-library/jest-dom @types/testing-library__jest-dom
```
2. Edit `vite.config.ts` file to be like this
```ts
/// <reference types="vitest" />

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
	plugins: [react()],
	test: {
		// now we can call test(), expect() in test files without needing to `import` them
		globals: true,

		// required environment to run RTL
		environment: 'jsdom',

		// a setup file where we will add more settings
		setupFiles: './src/setupTest.ts',

		// you might want to disable it, if you don't
		// have tests that rely on CSS since parsing CSS is slow
		css: true,
	},
})
```
3. Create `./src/setupTest.ts` file
```ts
import { afterEach, expect } from 'vitest'
import { cleanup } from '@testing-library/react'
import matchers from '@testing-library/jest-dom/matchers'

// enable `expect(...).toBeInTheDocument()`, etc.
expect.extend(matchers)

// unmount all components which are rendered by `render(...)`
afterEach(() => {
	cleanup()
})
```
4. The following is an example of a test file (`*.test.tsx`)
```ts
// `./src/Button.test.tsx`

import { Button } from './Button'
import { myFunction as mockMyFunction } from './myFunction'
import { render, screen } from '@testing-library/react'
import { vi, beforeEach } from 'vitest'
import userEvent from '@testing-library/user-event'
	
// how to mock a module using vitest
// assume that this module is used inside <Button/> comp
vi.mock('./myFunction', () => {
	return { myFunction: vi.fn(() => 'mock text') }
})

// other options are resetAllMocks(), restoreAllMocks()
beforeEach(() => {
	vi.clearAllMocks()
})

test('The first test', async () => {
	// how to mock a function using vitest
	const mockOnClick = vi.fn()
	
	render(<Button num={5} onClick={mockOnClick} />)
	expect(screen.getByText(/Something/)).toBeInTheDocument()
	await userEvent.click(screen.getByText(/Something/))
	
	// inspect the mocked module
	expect(mockMyFunction).toBeCalledTimes(1)
	expect(mockMyFunction).toBeCalledWith(5)
	// inspect the mocked function
	expect(mockOnClick).toBeCalledTimes(1)
	expect(mockOnClick).toBeCalledWith('mock text')
})
```
5. Run all tests
```bash
pnpm vitest
```
6. Optionally, add a new field in `scripts` (`package.json` file) and run the test with `pnpm run test` instead.
```json
"scripts": {
	// ...
	"test": "vitest"
},
```


Let's start a new SPA project using Vite, React, Typescript, Vitest and react-testing-library

[How to] Set up a React app with Vite

We will walk through steps to start a new Node.js project. The following are tools including in our project.

- vanilla javascript (no typescript)
- `eslint` for catching bugs
- `jest` for running tests

Note that we will use `commonjs` module instead of `esm` because `jest` does not fully support `esm` yet as of this writing(Feb, 2023).

## Steps

1. Initialize the project.
```bash
npm init
```
2. Install types for Node.js to make vscode intellisense works properly, e.g. while typing `process.env`, `require()`, etc.
```bash
npm install --save-dev @types/node
```
3. Initialize ESLint.
```bash
npm init @eslint/config
```
4. Select `commonjs` as a module, `node` as a runtime environment, and `javascript` language (not `typescript`).
5. Install Jest. Plus, install its type for vscode intellisense.
```bash
npm install --save-dev jest @types/jest
```
6. To make ESLint understands Jest's global variables such as `test()`, `expect()`, etc., edit `.eslintrc.js` file.
```js
env: {
	// ...
	jest: true, // <------ add this line
},
```
7. Make sure we don't have `"type": "module"` in `package.json` file since we want to use `commonjs`, not `esm`.
8. Write javascript as you want, every file is `*.js`. Test files are in `*.test.js` pattern.
9. Use `require()` and `module.exports`, not `import`/`export`.
10. Run any js file using `node filename.js`. Run tests using `npx jest`.

## For Typescript

- Replace `node` with `ts-node` or `tsx`(preferred)
- Replace `jest` with `ts-jest` or `vitest`
- Start with setting `tsconfig.json` to compile to `commonjs`



Vanilla Javascript, ESLint, and Jest

[How to] Setup a Node.js project

## Test 1: Normal paragraph

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. At elementum eu facilisis sed. Sagittis orci a scelerisque purus semper eget duis at tellus. Ornare massa eget egestas purus viverra accumsan in nisl nisi. Purus sit amet luctus venenatis lectus magna. Posuere ac ut consequat semper viverra nam libero justo. Facilisi cras fermentum odio eu. Morbi quis commodo odio aenean sed. Orci sagittis eu volutpat odio facilisis mauris sit. Tellus integer feugiat scelerisque varius morbi enim.

## Test 2: Vertical image

![test image](https://res.cloudinary.com/pob/image/upload/v1675773660/next-blog/prod/eguvbyhpbkpraty8th3t.png)

## Test 3: Horizontal image

![another test image](https://res.cloudinary.com/pob/image/upload/v1710876230/next-blog/prod/rg29bmxgkpo2q2fdgctw.png)

## Test 4: Long word trying to overflow horizontally

`112321312dfdafdsajdfdafdsafadfafdfljslafjlkdfadsf4456LoremipsumdolorsitametLoremipsumdolorsitamet112321312dfdafdsajdfdafdsafadfafdfljslafjlkdfadsf4456LoremipsumdolorsitametLoremipsumdolorsitamet` 112321312dfdafdsajdfdafdsafadfafdfljslafjlkdfadsf4456LoremipsumdolorsitametLoremipsumdolorsitamet112321312dfdafdsajdfdafdsafadfafdfljslafjlkdfadsf4456LoremipsumdolorsitametLoremipsumdolorsitamet

## Test 5: Heading

## Heading2

### Heading3

#### Heading4

##### Heading5

###### Heading6

## Test 6: Bullet points

- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. At elementum eu facilisis sed.
- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. At elementum eu facilisis sed. 
	  ```
	  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. At elementum eu facilisis sed. 
	  ```
- Lorem ipsum dolor sit amet  
	Lorem ipsum dolor sit amet  
	Lorem ipsum dolor sit amet 
- **Bold text** [link to Next.js](https://nextjs.org/)

1. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. At elementum eu facilisis sed.
    1. Lorem ipsum
    2. Lorem ipsum
        - Nested 
        - Another nested
2. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. At elementum eu facilisis sed. 

## Test 7: Code

```bash
npm i awesome-package
```

```js
let arr = [2, 3, 4]
for(let i = 0; i < arr.length; i++) {
  console.log(arr[i])
}
```

```jsx mdx:preview
import React from "react";
import MDEditor from '@uiw/react-md-editor';

export default function App() {
  const [value, setValue] = React.useState("**Hello world!!!**");
  return (
    <div className="container">
      <MDEditor
        value={value}
        onChange={setValue}
      />
      <MDEditor.Markdown source={value} style={{ whiteSpace: 'pre-wrap' }} />
    </div>
  );
}
```

## Test 8: Using image as a link

[![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?logo=codesandbox)](https://codesandbox.io/embed/markdown-editor-for-react-izdd6?fontsize=14&hidenavigation=1&theme=dark)

[![Open in Github gh-pages](https://img.shields.io/badge/Open%20In-Github%20gh--pages-blue?logo=github)](https://uiwjs.github.io/react-md-editor/)

[![Open in Gitee gh-pages](https://img.shields.io/badge/Open%20In-Gitee%20gh--pages-blue?logo=web)](https://uiw.gitee.io/react-md-editor/)

## Test 9: Arrows

- `->` will display as ->
- `-->` will display as -->
- `------>` will display as ------> (so, the max is 3 of `-`)
- `<-` is <-
- `<->` is <->

## Test 10: Links

Some random links: [nextjs](https://nextjs.org/). [`#52`](https://github.com/uiwjs/react-md-editor/issues/52#issuecomment-848969341) [`#224`](https://github.com/uiwjs/react-md-editor/issues/224#issuecomment-901112079)

## Test 11: Sequence of image as a link without a new line

[![Open in CodeSandbox](https://img.shields.io/badge/Open%20in-CodeSandbox-blue?logo=codesandbox)](https://codesandbox.io/embed/nextjs-example-react-md-editor-qjhn7?fontsize=14&hidenavigation=1&theme=dark) [![Open in StackBlitz](https://img.shields.io/badge/Open%20In-StackBlitz-green)](https://stackblitz.com/edit/nextjs-react-md-editor?embed=1&file=pages/index.js&hideExplorer=1&hideNavigation=1&theme=dark) [![#52](https://img.shields.io/github/issues/detail/state/uiwjs/react-md-editor/52)](https://github.com/uiwjs/react-md-editor/issues/52#issuecomment-848969341) [![#224](https://img.shields.io/github/issues/detail/state/uiwjs/react-md-editor/224)](https://github.com/uiwjs/react-md-editor/issues/224#issuecomment-901112079)

## Test 12: Strikethrough

- ~~`renderTextarea?: (props, opts) => JSX.Element;`~~: `@deprecated` Please use ~~`renderTextarea`~~ -> `components`. Use div to replace TextArea or re-render TextArea. [#193](https://github.com/uiwjs/react-md-editor/issues/193)
- `components`: re-render ~~textarea/toolbar element~~. [#419](https://github.com/uiwjs/react-md-editor/issues/419)
- `height?: number=200`: The height of the editor. ️⚠️ ~~`Dragbar` is invalid when **`height`** parameter~~ percentage.

## Test 13: Html tag

<a href="https://github.com/uiwjs/react-md-editor/graphs/contributors">
  <img src="https://uiwjs.github.io/react-md-editor/CONTRIBUTORS.svg" />
</a>

<p>Some paragraph text</p>

## Test 14: Horizontal line

---

Some text

---

## Test 15: Square image

![square img](https://res.cloudinary.com/pob/image/upload/v1710877271/next-blog/prod/jlhzutiwaumtv9irxssf.png)



CrispyScript

My Recent Posts