DEV Community: Anton Prudkohliad

OTP email verification and password reset

Anton Prudkohliad — Wed, 03 Dec 2025 12:19:54 +0000

I recently tried to implement a secure OTP-based email verification and password reset flow - only to realize how little concrete, end-to-end guidance is out there. Most write-ups simply skip the gritty parts because everyone seems to rely on external auth providers. I wanted something I could fully control, so I built a self-hosted solution from scratch while thinking carefully about OTP generation, hashing, crypto, race conditions and a smooth user experience.

⚠️ Disclaimer: These are just my personal notes and reflections, not exhaustive security guidance. Evaluate and adapt them to your own system requirements.

General considerations

Prevent email enumeration by making sure all requests take constant time. This can be implemented as a middleware that “sleeps” if a request takes less than a certain amount of time - e.g. 500ms.
Whenever you need to sign a JWT, use Public-key cryptography - e.g. ES256. This way you can avoid storing the sensitive key in your database. After the JWT has been signed, the private key can be discarded because for further verification you only need the public key.
Why ES256 over RS256? – ES256 is faster.
Only generate the OTPs right before sending it via email, so that its plaintext version (sensitive data) is not stored in your database. If you have to store it - probably better to encrypt it first using something like AES-256-GCM with key rotation.

Register

This endpoint will create a user record if it does not exist and schedule a background job that will generate and send an OTP to the email address provided by the user.

mermaid code

sequenceDiagram
  participant user as User
  participant api as API
  participant db as DB
  participant job as Background Worker

  user->>api: Register
  api->>db: Open transaction
  db->>api:
  api->>db: Find user by email FOR UPDATE NOWAIT
  db->>api:
  alt user does not exist
    api->>db: Create user
    db->>api:
    alt failed to insert because of the unique email constraint
        api->>user: HTTP 204
    end
  end
  api->>api: Check if email already verified
  alt email already verified
      api->>user: HTTP 204
  end
  api->>api: Check OTP cooldown
  alt cooldown not complete
      api->>user: HTTP 204
  end
  api->>db: Reset hashed OTP, cooldown and attempts
  db->>api:
  api->>db: Commit transaction
  db->>api:
  api->>job: Schedule Background Job
  job->>api:
  api->>user: HTTP 204
  job->>job: Generate OTP
  job->>db: Store hashed OTP
  db->>job:
  job-->>user: Send plaintext OTP via email

⚠️ Important:

HTTP 204 No Content is returned always in order to prevent email enumeration
During each request the current OTP hash will be overwritten by a new one. So a legitimate user might be locked of verification if an attacker is hammering the register endpoint with the user’s email address. This is mitigated by introducing a “cooldown” a.k.a. rate limit.
Mitigate race condition (two or more requests trying to create the user at the same time) in the database by SELECT -ing the user record with FOR UPDATE NOWAIT – and handling the Postgres error 55P03 (If you’re using Rails –ActiveRecord::LockWaitTimeout error will be raised) by returning HTTP 204 – before resetting the hashed OTP, cooldown and attempts, so that parallel requests do not trigger more than one background job

Resend verification email

mermaid code

sequenceDiagram
  participant user as User
  participant api as API
  participant db as DB
  participant job as Background Worker

  user->>api: Request verification
  api->>db: Open transaction
  db->>api:
  api->>db: Find user by email FOR UPDATE NOWAIT
  db->>api:
  alt user does not exist
      api->>user: HTTP 204
  end
  api->>api: Check if email already verified
  alt email already verified:
      api->>user: HTTP 204
  end
  api->>api: Check OTP cooldown
  alt cooldown not complete
      api->>user: HTTP 204
  end
  api->>db: Reset hashed OTP, cooldown, attempts and time window
  db->>api:
  api->>db: Commit transaction
  db->>api:
  api->>job: Schedule Background Job
  job->>api:
  api->>user: HTTP 204
  job->>job: Generate OTP
  job->>db: Store hashed OTP
  db->>job:
  job-->>user: Send plaintext OTP via email

⚠️ Important:

Everything from “Register” applies here as well, except that we don’t create a user record if it does not exist.

Verify email address with OTP

mermaid code

sequenceDiagram
    participant user as User
    participant api as API 
    participant db as DB

    user->>api: Send OTP and the email address
    api->>db: Find user by email
    db->>api:
    alt user not found
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check number of attempts
    alt too many attempts
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check if verification has been requested (email_verification_expires_at is not null)
    alt verification was not requested
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check if verification time window has ended
    alt time window has expired
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Compare stored OTP hash with received one
    alt hashes do not match
            api->>db: Increment attempts counter
            db->>api:
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check if email is already verified
    alt email verified
      api->>user: HTTP 422: already_verified
    end
    api->>db: Open transaction
    db->>api:
    api->>db: Clean OTP state (hash, attempts, expires_at)
    db->>api:
    api->>db: Mark User's email as verified
    db->>api:
    api->>db: Commit transaction
    db->>api:
    api->>api: Generate session tokens
    api->>db: Store tokens
    db->>api:
    api->>user: Return session tokens

⚠️ Important:

HTTP 422: invalid_otp is returned always in order to prevent email enumeration.
If the OTP is valid, but the email is already verified – the endpoint returns HTTP 422: already_verified. This does not lead to email enumeration, because at this point we have already authenticated the user by verifying their OTP.
It is safe (and user-friendly) to login the user in the end.

Request password reset

mermaid code

sequenceDiagram
  participant user as User
  participant api as API
  participant db as DB
  participant job as Background Worker

  user->>api: Request password reset
  api->>db: Open transaction
  db->>api:
  api->>db: Find user by email FOR UPDATE NOWAIT
  db->>api:
  alt user does not exist
      api->>user: HTTP 204
  end
  api->>api: Check password reset cooldown
  alt cooldown not complete
      api->>user: HTTP 204
  end
  api->>db: Reset hashed OTP, cooldown, attempts and time window
  db->>api:
  api->>db: Commit transaction
  db->>api:
  api->>job: Schedule Background Job
  job->>api:
  api->>user: HTTP 204
  job->>job: Generate OTP
  job->>db: Store hashed OTP
  db->>job:
  job-->>user: Send plaintext OTP via email

Verify password reset OTP

In order to improve the user experience, the password verification flow is split into two steps:

Verify password reset OTP (this endpoint)
Reset password (read further)

The former is used to exchange the OTP for a JWT, that is sent to the latter, along with the new password.

mermaid code

sequenceDiagram
    participant user as User
    participant api as API 
    participant db as DB

    user->>api: Send OTP and the email address
    api->>db: Find user by email
    db->>api:
    alt user not found
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check number of attempts
    alt too many attempts
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check if reset was requested (password_reset_expires_at is not null)
    alt reset was not requested
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Check if reset time window has ended
    alt time window has expired
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Compare stored OTP hash with received one
    alt hashes do not match
            api->>db: Increment attempts counter
            db->>api:
        api->>user: HTTP 422: invalid_otp
    end
    api->>api: Generate key pair for reset token
    api->>db: Clean OTP state (hash, attempts, expires_at), store reset token public key
    db->>api:
    api->>api: Build reset token JWT - sign with private key
    api->>user: Return reset token

Reset password

Use the token returned by the endpoint above to set up a new password.

mermaid code

sequenceDiagram
  participant user as User
  participant api as API
  participant db as DB

  user->>api: Send password reset token, new password
  api->>db: Find user (and token public key) by id from token
  db->>api:
  alt user not found
      api->>user: HTTP 422: invalid_token
  end
  api->>api: Check if token is valid (signature, expiration)
  alt token not valid
      api->>user: HTTP 422: invalid_token
  end
  api->>api: Hash new password
  api->>db: Store new password hash, clean reset token public key
  db->>api:
  api->>api: Generate session tokens
  api->>db: Store tokens
  db->>api:
  api->>user: Return session tokens

User properties

Only relevant ones are shown

Field Name	Type	Description
`email`	string	Email address
`email_verified_at`	timestamp	Time when the email address was verified
`email_verification_otp_digest`	string	Hashed version of OTP
`email_verification_expires_at`	timestamp	Until when an OTP can be used
`email_verification_otp_attempts`	integer	How many unsuccessful attempts to submit OTP there were
`email_verification_cooldown_resets_at`	timestamp	When a new OTP can be requested
`email_verification_last_requested_at`	timestamp	When the last OTP was requested (nice to have for audit log)
`password_reset_token_public_key`	byte array	Public key for the password-reset token
`password_reset_otp_digest`	string	Hashed version of OTP
`password_reset_expires_at`	timestamp	Until when an OTP can be used
`password_reset_otp_attempts`	integer	How many unsuccessful attempts to submit OTP there were
`password_reset_cooldown_resets_at`	timestamp	When a new OTP can be requested
`password_reset_last_requested_at`	timestamp	When the last OTP was requested (nice to have for audit log)

Getting Wi-Fi SSID on Mac via bash using Shortcuts

Anton Prudkohliad — Tue, 11 Nov 2025 22:23:32 +0000

Recent macOS releases restrict direct access to Wi-Fi details like SSID and BSSID for privacy reasons. Commands such as airport are deprecated, and modern tools like wdutil often return redacted values unless run with elevated privileges. Also check out this great post by Dan K. Snelson.

Shortcuts app

The reliable, Apple-supported solution is to use the Shortcuts app.

Shortcuts app in Spotlight

Create a new Shortcut and make sure you’re using the “Get Network Details” node with “Wi-Fi” and “Network Name” arguments. Then connect it to another node “Stop and output”.

Get Wi-Fi SSID Shortcut

Getting output in Bash

⚠️ When you first run the command, MacOS will request permissions.

For some reason the command by itself does not return anything, but when paired with capturing – it will output your SSID:

$ shortcuts run "Get Wi-Fi SSID"
$ output=$(shortcuts run "Get Wi-Fi SSID")
$ echo $output
Anton’s iPhone

You can then use this in your rc file for scripting 👌

How to check SSL/TLS cipher suites on your website with nmap

Anton Prudkohliad — Tue, 22 Jul 2025 10:32:38 +0000

Prerequisites

Install nmap

The check

The command you want to run is:

nmap --script ssl-enum-ciphers -p 443 example.com

For example, for my website:

nmap --script ssl-enum-ciphers -p 443 prudkohliad.com

I am currently getting the following output:

Starting Nmap 7.97 ( https://nmap.org ) at 2025-07-22 09:49 +0100
Nmap scan report for prudkohliad.com (172.67.203.165)
Host is up (0.0068s latency).
Other addresses for prudkohliad.com (not scanned): 104.21.52.204 2606:4700:3037::6815:34cc 2606:4700:3035::ac43:cba5

PORT    STATE SERVICE
443/tcp open  https
| ssl-enum-ciphers:
|   TLSv1.2:
|     ciphers:
|       TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA (ecdh_x25519) - A
|       TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 (ecdh_x25519) - A
|       TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (ecdh_x25519) - A
|       TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA (ecdh_x25519) - A
|       TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 (ecdh_x25519) - A
|       TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 (ecdh_x25519) - A
|       TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (ecdh_x25519) - A
|       TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (ecdh_x25519) - A
|       TLS_RSA_WITH_AES_128_CBC_SHA (rsa 2048) - A
|       TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa 2048) - A
|       TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048) - A
|       TLS_RSA_WITH_AES_256_CBC_SHA (rsa 2048) - A
|       TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa 2048) - A
|       TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048) - A
|     compressors:
|       NULL
|     cipher preference: client
|   TLSv1.3:
|     ciphers:
|       TLS_AKE_WITH_AES_128_GCM_SHA256 (ecdh_x25519) - A
|       TLS_AKE_WITH_AES_256_GCM_SHA384 (ecdh_x25519) - A
|       TLS_AKE_WITH_CHACHA20_POLY1305_SHA256 (ecdh_x25519) - A
|     cipher preference: client
|_  least strength: A

Nmap done: 1 IP address (1 host up) scanned in 1.37 seconds

Now you can compare these with your requirements and disable the insecure ones.

Have fun 😉

How to implement a Multi-Select Dropdown component with React and Tailwind 4

Anton Prudkohliad — Wed, 05 Feb 2025 08:42:50 +0000

Recently I stumbled upon one of Web Dev Cody's videos where he was implementing a Multi-Select Dropdown component. So, I decided to write my own one, but with a twist — also make it work when JavaScript is disabled 🤓. So I ended up using the Checkbox Hack and the old-school form action attribute. Let walk through the implementation from creating the initial HTML markup to adding some progressive enhancements such as “Select All” and “Clear Selection” buttons if the JavaScript is enabled in the browser.

The end result will look like this:

The Multi-Select Dropdown

Prerequisites

I’ll skip the boring part such as setting up the project and adding Tailwind 4 to it. Instead, please use the following links as a reference:

How to set up a new project using Yarn
Next.js manual installation
Styling: Tailwind CSS in Next.js
[Upgrading your Tailwind CSS projects from v3 to v4](https://tailwindcss.com/docs/upgrade-guide(https://tailwindcss.com/docs/upgrade-guide)

I also created a GitHub repository, you can follow from this commit.

The design

The design of the Multi-Select Dropdown component

As you can see from the image, there are two main parts of the component: the “toggle” (the panel where it says “11 selected”) and the dropdown part with the list of options.

The skeleton

First, create the component in the src/components directory:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown() {
  return (
    <label className="relative">
      <input type="checkbox" className="hidden peer" />

      <div className="cursor-pointer after:content-['▼'] after:text-xs after:ml-1">
        {"Show the dropdown"}
      </div>

      <div className="hidden peer-checked:flex absolute bg-white border border-gray-200">
        {"Welcome to the dropdown"}
      </div>
    </label>
  );
}

Here’s the Checkbox Hack. Notice the hidden input of type checkbox. It makes the input invisible, but since it’s enclosed inside a label, any click on the label will flip it’s state. Then, we style the sibling based on the state of the hidden checkbox using the peer and peer-checked:flex classes from Tailwind CSS. Initially the dropdown is hidden, but if the checkbox is checked, the dropdown is going to show up.

I also added a triangle after the “Show the dropdown” text to indicate that this is indeed a dropdown 🙌.

Next, create a page, so that there is a place to display the component:

// src/app/page.js

import MultiSelectDropdown from "../components/MultiSelectDropdown";

export default function Page() {
  return (
    <>
      <h1>{"Multi-Select Dropdown"}</h1>
      <form>
        <MultiSelectDropdown />
        <input type="submit" />
      </form>
    </>
  );
}

This is what the result so far should look like:

Initial markup behavior recording

Smooth transitions

This is an optional step 💅. I just added some animations to the dropdown:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown() {
  return (
    <label className="relative">
      <input type="checkbox" className="hidden peer" />

      <div className="cursor-pointer after:content-['▼'] after:text-xs after:ml-1 after:inline-flex after:items-center peer-checked:after:-rotate-180 after:transition-transform">
        {"Show the dropdown"}
      </div>

      <div className="absolute bg-white border border-gray-200 p-2 transition-opacity opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto">
        {"Welcome to the dropdown"}
      </div>
    </label>
  );
}

For the toggle div I added classes after:inline-flex after:items-center peer-checked:after:-rotate-180 after:transition-transform so that the triagle rotates by 180 degrees smoothly when the dropdown opens.

I also changed how the dropdown is hidden. Instead of changing the display: none to display: flex (hidden and peer-checked:flex classes), the component is now transparent and does not respond to pointer events by default, but when the toggle is on, it becomes 100% opaque and starts responding to pointer events: opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto. There’s also a class for smooth opacity transition — transition-opacity.

What it looks like with smooth transitions:

Smooth transitions added

Rendering the options

Of course, it would be great for our component to actually display the available options. So let’s pass options to our component as props. Additionally, for the array of selected options to be submittable to the backend, let’s pass the input name as formFieldName prop as well:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown({ formFieldName, options }) {
    // ...
}

Now, let’s render each option as a label with an input of type checkbox instead of the {"Welcome to the dropdown"} part:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown({ formFieldName, options }) {
  return (
    <label className="relative">
      <input type="checkbox" className="hidden peer" />
        {"Show the dropdown"}
      </div>

      <div className="absolute bg-white border border-gray-200 transition-opacity opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto">
        <ul>
          {options.map((option, i) => {
            return (
              <li key={option}>
                <label className="flex whitespace-nowrap cursor-pointer px-2 py-1 transition-colors hover:bg-blue-100 [&:has(input:checked)]:bg-blue-200">
                  <input
                    type="checkbox"
                    name={formFieldName}
                    value={option}
                    className="cursor-pointer"
                  />
                  <span className="ml-1">{option}</span>
                </label>
              </li>
            );
          })}
        </ul>
      </div>
    </label>
  );

Notice that we don’t need to specify the for attribute on the label tags — that’s because the inputs are inside of labels, just like in the Checkbox Hack. We are also adding some styling here, which is pretty standard Tailwind CSS stuff like hover color change and smooth transitions.

And let’s also pass the actual options and form field name to the component instance (we are going to use a list of totally randomly selected countries):

// src/app/page.js

const COUNTRIES = [ "Austria", "Belgium", "Croatia", "Bulgaria", "Cyprus", "Czech Republic", "Denmark", "Estonia", "Finland", "France", "Germany", "Greece", "Hungary", "Ireland", "Italy", "Latvia", "Lithuania", "Luxembourg", "Malta", "Netherlands", "Poland", "Portugal", "Romania", "Slovakia", "Slovenia", "Spain", "Sweden", "Ukraine"];

export default function Page() {
  return (
    <>
      <h1>{"Multi-Select Dropdown"}</h1>
      <form>
        <MultiSelectDropdown formFieldName={"countries"} options={COUNTRIES} />
        <input type="submit" />
      </form>
    </>
  );
}

Now we finally can see the list of the options in the dropdown:

Dropdown with options

Testing the form submission

We are also going to need some way to test if the input works, so let’s create an API endpoint (a Route Handler) that will read all the selected countries from the submitted form and print them to the server logs.

To do that, we will create another folder in the src/app directory called api and then create a route.js file inside.

In this file we are going to export an async function called POST that will read the form data from the request, getAll the countries from the form data, and print them out:

// src/app/api/route.js 

export async function POST(request) {
  const formData = await request.formData();
  const countries = formData.getAll("countries");

  console.debug("countries", countries);

  return new Response("All good", { status: 200 });
}

We also need to make sure that the form is submitted to this endpoint, so let’s add action="/api" and method="post" to our form tag:

// src/app/page.js

// ...

export default function Page() {
  return (
    <>
      <h1>{"Multi-Select Dropdown"}</h1>
      <form action="/api" method="post">
        <MultiSelectDropdown formFieldName={"countries"} options={COUNTRIES} />
        <input type="submit" />
      </form>
    </>
  );
}

Now, when you go to the dropdown, select a couple of countries, and click “Submit”, you should be able to see the list of the countries that you have selected in the server logs:

Server logs with the list of selected countries

Handling changes

Let’s also make sure that there’s a way to inform the parent component about the changes in the selection by introducing an onChange prop and calling this function whenever the state of any checkbox changes.

Since onChange is an event handler and we are using Next.js with all the SSR and SSG quirks, we are also going to need to add a "use client" directive at the top.

We are also going to need the selectedOptions state to keep track of what the user has already selected:

// src/components/MultiSelectDropdown.jsx

"use client";

import { useState } from "react";

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange,
}) {
  const [selectedOptions, setSelectedOptions] = useState([]);

  // ...
}

Then, every time any input is checked or unchecked, we need to update the selectedOptions accordingly and call the onChange callback:

// src/components/MultiSelectDropdown.jsx

// ...

const handleChange = (e) => {
  const isChecked = e.target.checked;
  const option = e.target.value;

  const selectedOptionSet = new Set(selectedOptions);

  if (isChecked) {
    selectedOptionSet.add(option);
  } else {
    selectedOptionSet.delete(option);
  }

  const newSelectedOptions = Array.from(selectedOptionSet);

  setSelectedOptions(newSelectedOptions);
  onChange(newSelectedOptions);
};

// ...

Do not forget to pass the handleChange function as onChange handler to every input that is rendered:

// src/components/MultiSelectDropdown.jsx

// ...

options.map((option, i) => {
  return (
    <li key={option}>
      <label className="flex whitespace-nowrap cursor-pointer px-2 py-1 transition-colors hover:bg-blue-100 [&:has(input:checked)]:bg-blue-200">
        <input
          type="checkbox"
          name={formFieldName}
          value={option}
          className="cursor-pointer"
          onChange={handleChange}
        />
        <span className="ml-1">{option}</span>
      </label>
    </li>
  );
})

// ...

And let’s pass a debugger function to the component instance so that we can test that it works:

{/* src/app/page.js */}

{/* ... */}

<MultiSelectDropdown
  formFieldName={"countries"}
  options={COUNTRIES}
  onChange={(selectedCountries) => {
    console.debug("selectedCountries", selectedCountries);
  }}
/>

{/* ... */}

Now the array of selected options should be printed out every time the selection changes:

Selection changes reflected in the console

Select all and Clear selection

It would be also nice to add some helper buttons for the user to be able to quickly select all the options and to quickly reset the selection.

To progressively show the buttons only when JavaScript is enabled, we need to introduce a state value that will be initially false but on the initialization of the component will become true. I am going to call it isJsEnabled and will set it to true in a useEffect hook.

Also, this would be a good time to introduce such derived variables as isSelectAllEnabled and isClearSelectionEnabled which will help us to enable or disable the according buttons. The former will be true unless the number of selected items is the same as the number of all available options. The latter will be true if the number of selected items is greater than zero.

// src/components/MultiSelectDropdown.jsx

"use client";

import { useState, useEffect } from "react";

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange
}) {
  const [isJsEnabled, setIsJsEnabled] = useState(false);
  const [selectedOptions, setSelectedOptions] = useState([]);

  useEffect(() => {
    setIsJsEnabled(true);
  }, []);

  const isSelectAllEnabled = selectedOptions.length < options.length;
  const isClearSelectionEnabled = selectedOptions.length > 0;

  // ...
}

Since the inputs are uncontrolled, we are going to need a way to find all the inputs and update the checked attribute. To do that, I am going to introduce a ref that would store the pointer to the options list DOM element:

// src/components/MultiSelectDropdown.jsx

"use client";

import { useState, useEffect, useRef } from "react";

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange
}) {
  // ...

  const optionsListRef = useRef(null);

  // ...

  return (
    <label className="relative">
      {/* ... */}

      <div className="absolute bg-white border border-gray-200 transition-opacity opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto">
        {/* ... */}
        <ul ref={optionsListRef}>
          {options.map((option, i) => {/* ... */}
        </ul>
      </div>
    </label>
  );
}

Now we can write the two helper functions that would go through all the inputs inside of the optionsListRef, update the checked attribute, update the selectedOptions state, and call the onChange callback:

// src/components/MultiSelectDropdown.jsx

// ...

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange
}) {
  // ...

    const handleSelectAllClick = (e) => {
      e.preventDefault();

      const optionsInputs = optionsListRef.current.querySelectorAll("input");
      optionsInputs.forEach((input) => {
        input.checked = true;
      });

      setSelectedOptions([...options]);
      onChange([...options]);
    };

    const handleClearSelectionClick = (e) => {
      e.preventDefault();

      const optionsInputs = optionsListRef.current.querySelectorAll("input");
      optionsInputs.forEach((input) => {
        input.checked = false;
      });

      setSelectedOptions([]);
      onChange([]);
    };

  // ...
}

Do not forget to bind the functions to the according buttons:

{/* src/components/MultiSelectDropdown.jsx */}

{/* ... */}

<ul>
  <li>
    <button
      onClick={handleSelectAllClick}
      disabled={!isSelectAllEnabled}
      className="w-full text-left px-2 py-1 text-blue-600 disabled:opacity-50"
    >
      {"Select All"}
    </button>
  </li>
  <li>
    <button
      onClick={handleClearSelectionClick}
      disabled={!isClearSelectionEnabled}
      className="w-full text-left px-2 py-1 text-blue-600 disabled:opacity-50"
    >
      {"Clear selection"}
    </button>
  </li>
</ul>

{/* ... */}

Now it should be much easier to select all the elements at once or to reset the selection.

And if you disable JavaScript, the buttons won’t show up, but the component will still function:

Helper buttons are hidden when JavaScript is disabled

Wrapping up

That was a lot. I won’t be adding the polishing steps here, you can find them in the GitHub repository.

I would also like to point out that the form action attribute is not the usual way to handle form submissions in Next.js. It is used in this post just to demonstrate that it is possible to implement such a component without using browser JavaScript. The recommended ways to submit forms via Next.js are Server Actions or the plain old Fetch API.

Feedback

If you have any feedback, please feel free to write a comment.

My original blog post

Updating website content on schedule via GitHub Actions

Anton Prudkohliad — Sat, 17 Aug 2024 05:21:31 +0000

I would like to share my journey on building a self-sustainable content management system that does not require a content database in a traditional sense.

The Problem

The content (blog posts and bookmarks) of this website is stored in a Notion database:

The database with bookmarks – Notion UI

The problem that I was trying to solve was to not have to deploy the website manually after each bookmark that I add there. And on top of that – keep the hosting as cheap as possible, because for me it does not really matter how fast the bookmarks that I add to my Notion database end up online.

So, after some research I came up with the following setup:

A high-level overview of the content delivery mechanism

The system consists of several components:

The “Push to Main” action that deploys the changes
The “Update Content” action that downloads content from Notion API and commits the changes
The “Update Content on Schedule” action runs once in a while and triggers the “Update Content” action

Let us look into each one of them from the inside out in detail.

The “Push to Main” Workflow

There is not a lot to say here, pretty standard setup, – when there is a push to the main branch, this workflow builds the app and deploys it to Cloudflare Pages using the Wrangler CLI:

name: Push to Main
on:
  push:
    branches: [main]
  workflow_dispatch: {}
jobs:
  deploy-cloudflare-pages:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version-file: .node-version
          cache: pnpm
      - name: Install node modules
        run: |
          pnpm --version
          pnpm install --frozen-lockfile
      - name: Build the App
        run: |
          pnpm build
      - name: Publish Cloudflare Pages
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm wrangler pages deploy ./out --project-name ${{ secrets.CLOUDFLARE_PROJECT_NAME }}

The “Update Content” Workflow

This Workflow can only be triggered “manually”… but also automatically because you can trigger it using a GitHub Personal Access Token, a.k.a. PAT. I initially wrote it because I wanted to deploy changes from my phone. It downloads the posts and bookmarks using the Notion API and then – if there are any change to the codebase – creates a commit and pushes it. In order to function properly, this workflow must be provided with a PAT that has “Read and Write access to code” of the repository:

name: Update Content
on:
  workflow_dispatch: {}
jobs:
  download-content:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # A Github Personal Access Token with access to the repository 
          # that has the follwing permissions:
          # ✅ Read and Write access to code
          token: ${{ secrets.GITHUB_PAT_CONTENT }}
      - name: Setup pnpm
        uses: pnpm/action-setup@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version-file: .node-version
          cache: pnpm
      - name: Install node modules
        run: |
          pnpm --version
          pnpm install --frozen-lockfile
      - name: Download articles content from Notion
        env:
          NOTION_KEY: "${{ secrets.NOTION_KEY }}"
          NOTION_ARTICLES_DATABASE_ID: "${{ secrets.NOTION_ARTICLES_DATABASE_ID }}"
        run: |
          pnpm download-articles
      - name: Download bookmarks content from Notion
        env:
          NOTION_KEY: ${{ secrets.NOTION_KEY }}
          NOTION_BOOKMARKS_DATABASE_ID: ${{ secrets.NOTION_BOOKMARKS_DATABASE_ID }}
        run: |
          pnpm download-bookmarks
      - name: Configure Git
        run: |
          git config --global user.email "${{ secrets.GIT_USER_EMAIL }}"
          git config --global user.name "${{ secrets.GIT_USER_NAME }}"
      - name: Check if anything changed
        id: check-changes
        run: |
          if [ -n "$(git status --porcelain)" ]; then
            echo "There are changes"
            echo "HAS_CHANGED=true" >> $GITHUB_OUTPUT
          else
            echo "There are no changes"
            echo "HAS_CHANGED=false" >> $GITHUB_OUTPUT
          fi
      - name: Commit changes
        if: steps.check-changes.outputs.HAS_CHANGED == 'true'
        run: |
          git add ./src/content
          git add ./public
          git commit -m "Automatic content update commit"
          git push

The “Update Content on Schedule” Workflow

This one is pretty simple: it just runs every once in a while and triggers the workflow above. In order to function properly, this workflow must be provided with a GitHub PAT that has “Read and Write access to actions” of the repository. In my case it’s a different PAT:

name: Update Content on Schedule
on:
  schedule:
    - cron: "13 0,12 * * *"
  workflow_dispatch: {}
jobs:
  trigger-update-content:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Dispatch the Update Content workflow
        env:
          # A Github Personal Access Token with access to the repository 
          # that has the follwing permissions:
          # ✅ Read and Write access to actions
          GH_TOKEN: ${{ secrets.GITHUB_PAT_ACTIONS }}
        run: |
          gh workflow run "Update Content" --ref main

Conclusion

For me this setup has proven to be really good and flexible. Because of the modular structure, the “Update Content” action can be triggered manually – e.g. from my phone while travelling. To me this was another valuable experience of progressive enhancement of a workflow.

Hope you find this helpful 😉

How to deploy a Next.js app to a Hetzner VPS using SST and Docker

Anton Prudkohliad — Tue, 13 Aug 2024 06:02:00 +0000

My original blog post: https://www.prudkohliad.com/articles/deploy-next-js-to-vps-using-sst-2024-08-11

SST is a framework that makes it easy to build modern full-stack applications on your own infrastructure. SST v3 uses Pulumi and Terraform
– SST Documenation

In this guide we will be deploying a Next.js app on a Hetzner VPS using SST and Docker. This guide is a follow-up on my previous post. If you find something that does not make sense here, there’s a good chance you’ll find the answers there – How to deploy a Next.js app to a VPS on Hetzner using Docker and GitHub Actions.

Add SST to the project

To add SST to the project, run the following command:

pnpx sst@ion init

This will show an interactive prompt. Select “Yes” and then “aws”:

SST init output – Terminal

Make sure all the necessary packages are installed:

pnpm install

This will create the sst.config.ts file where we will be adding all the configuration.

Also, some other files/directories will be created. Let’s add them to .dockerignore, we don’t want them to end up the the Docker image:

# sst
.sst
sst.config.ts
tsconfig.json

This is what the sst config file looks like currently:

/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "next-self-hosted",
      removal: input?.stage === "production" ? "retain" : "remove",
      home: "aws",
    };
  },
  async run() {},
});

We are not going to use AWS, so let’s set the home parameter to "local":

/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "next-self-hosted",
      removal: input?.stage === "production" ? "retain" : "remove",
      home: "local",
    };
  },
  async run() {},
});

Now can start adding things to the run() function.

Create an API Token on Hetzner

In order to create a VPS on Hetzner using SST, we are going to need a Hetzner API Token. Let’s generate a new one.

Open the project in Hetzner console, navigate to the “Security” tab:

Project Security settings – Hetzner Cloud UI

Generate an API token:

Generating an API token – Hetzner Cloud UI

A new token will be added to you project:

The API token – Hetzner Cloud UI

The token will only be shown once, make sure to not lose it.

Add TLS and Hetzner Providers:

pnpm sst add tls
pnpm sst add hcloud
pnpm install

Generate an SSH key

In order to execute further commands after we create a Hetzner VPS, we need to make sure that an SSH key is added to it during the creation. To do that, we will create an SSH token locally and then add it’s public part to Hetzner. Add the following code to the run function:

// In the run() function:

// Generate an SSH key
const sshKeyLocal = new tls.PrivateKey("SSH Key - Local", {
  algorithm: "ED25519",
});

// Add the SSH key to Hetzner
const sshKeyHetzner = new hcloud.SshKey("SSH Key - Hetzner", {
  publicKey: sshKeyLocal.publicKeyOpenssh,
});

Deploy the app:

pnpm sst deploy

SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     SSH Key - Local tls:index:PrivateKey
|  Created     SSH Key - Hetzner hcloud:index:SshKey

✓  Complete

You will see that a new SSH key has been added to Hetzner:

The SSH key – Hetzner Cloud UI

Now we can proceed with creating a VPS.

Create a Server

The following command will ensure that a new VPS is created in your project:

// In the run() function:

// Create a Server on Hetzner
const server = new hcloud.Server("Server", {
  image: "docker-ce",
  serverType: "cx22",
  location: "nbg1",
  sshKeys: [sshKeyHetzner.id],
});

Here I am using docker-ce image, because it comes with Docker already installed. You can use Hetzner Cloud API to list all the available images, server types and datacenters.

Verify that the server gets created correctly:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     Server hcloud:index:Server (34.5s)

✓  Complete

You should also be able to see the newly created server in the console:

The Server – Hetzner Cloud UI

Connect to Docker Server on the VPS

In order to build the app Docker image on the VPS and be able to create networks, volumes and containers, we need to make a bridge between our local machine and Docker Server on the VPS. To do that, we are going to need the Docker provider:

pnpm sst add docker
pnpm install

Store the private SSH key on disk so that the SSH client can access it. Сreate a connection to the Docker server on the VPS:

// At the top of the file:
import { resolve as pathResolve } from "node:path";
import { writeFileSync as fsWriteFileSync } from "node:fs";

// In the run() function:

// Store the private SSH Key on disk to be able to pass it to the Docker
// Provider
const sshKeyLocalPath = sshKeyLocal.privateKeyOpenssh.apply((k) => {
  const path = "id_ed25519_hetzner";
  fsWriteFileSync(path, k, { mode: 0o600 });
  return pathResolve(path);
});

// Connect to the Docker Server on the Hetzner Server
const dockerServerHetzner = new docker.Provider("Docker Server - Hetzner", {
  host: $interpolate`ssh://root@${server.ipv4Address}`,
  sshOpts: ["-i", sshKeyLocalPath, "-o", "StrictHostKeyChecking=no"],
});

Make sure to also add the private SSH key id_ed25519_hetzner to .gitignore and .dockerignore, so that it does not make it into your GitHub repo and to the Docker image.

Trigger the deployment to verify the changes:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     Docker Server - Hetzner pulumi:providers:docker

✓  Complete

Build the Docker image

Now we can build the Docker image on the remove Docker server:

// In the run() function:

// Build the Docker image
const dockerImageHetzner = new docker.Image(
  "Docker Image - App - Hetzner",
  {
    imageName: "next-self-hosted/next-self-hosted:latest",
    build: {
      context: pathResolve("./"),
      dockerfile: pathResolve("./Dockerfile"),
      target: "production",
      platform: "linux/amd64",
    },
    skipPush: true,
  },
  {
    provider: dockerServerHetzner,
    dependsOn: [server],
  }
);

Let’s trigger the deployment to see if everything works:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Log         Starting Docker build
< ... A PRETTY LONG BUILD LOG HERE ... >
|  Log         Image built successfully, local id "sha256:629a6cdfc298c74599a3056278e31c64197a87f6d11aab09573bc9171d2f3362"
|  Created     Docker Image - App - Hetzner docker:index:Image (36.0s)

✓  Complete

Now, let’s check that Docker image made it to the server:

ssh root@116.203.183.180 -i ./id_ed25519_hetzner -o StrictHostKeyChecking=no -C "docker image ls"
REPOSITORY                          TAG       IMAGE ID       CREATED              SIZE
next-self-hosted/next-self-hosted   latest    629a6cdfc298   About a minute ago   712MB

Awesome!

Docker networks

We will create two networks: Public and Internal. The Public network is for services to which NGINX is connected, i.e. for services that have to be exposed to the outside (e.g. the Next.js application or an API server). The Internal network is for services that are not meant to be exposed to the outside e.g. Postgres database, Redis cache:

// In the run() function:

// Setup Docker Networks
const dockerNetworkPublic = new docker.Network(
  "Docker Network - Public",
  { name: "app_network_public" },
  { provider: dockerServerHetzner, dependsOn: [server] }
);
const dockerNetworkInternal = new docker.Network(
  "Docker Network - Internal",
  { name: "app_network_internal" },
  { provider: dockerServerHetzner, dependsOn: [server] }
);

Trigger the deployment:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     Docker Network - Public docker:index:Network (2.3s)
|  Created     Docker Network - Internal docker:index:Network (3.1s)

✓  Complete

Check that networks app_network_internal and app_network_public are present on the remote:

ssh root@116.203.183.180 -i ./id_ed25519_hetzner -o StrictHostKeyChecking=no -C "docker network ls"
NETWORK ID     NAME                   DRIVER    SCOPE
0590360bd4ae   app_network_internal   bridge    local
e3bd8be72506   app_network_public     bridge    local
827fa5ca5de2   bridge                 bridge    local
dc8880514199   host                   host      local
f1481867db18   none                   null      local

Docker volumes

We will create a volume to store the application build files (the .next folder):

// In the run() function:

// Setup Docker Volumes
const dockerVolumeAppBuild = new docker.Volume(
  "Docker Volume - App Build",
  { name: "app_volume_build" },
  { provider: dockerServerHetzner, dependsOn: [server] }
);

Deploy and verify that the docker volume app_volume_build is present on the VPS:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     Docker Volume - App Build docker:index:Volume

✓  Complete

ssh root@116.203.183.180 -i ./id_ed25519_hetzner -o StrictHostKeyChecking=no -C "docker volume ls"
DRIVER    VOLUME NAME
local     app_volume_build

The Build container

We are going to run a one-off container (a.k.a. Init Container) to build the Next.js application and store the result in the .next folder, that will be shared with the main application container through the volume that we have created above:

// In the run() function:

// Run a one-off container to build the app
const dockerAppBuildContainer = new docker.Container(
  "Docker Container - App Build",
  {
    name: "app_container_build",
    image: dockerImageHetzner.imageName,
    volumes: [
      {
        volumeName: dockerVolumeAppBuild.name,
        containerPath: "/app/.next",
      },
    ],
    command: ["pnpm", "build"],
    mustRun: true,
  },
  {
    provider: dockerServerHetzner,
  }
);

Deploy and verify via logs that the build has been successful:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     Docker Container - App Build docker:index:Container (1.1s)

✓  Complete

ssh root@116.203.183.180 -i ./id_ed25519_hetzner -o StrictHostKeyChecking=no -C "docker logs -f app_container_build"

> next-self-hosted@ build /app
> next build

  ▲ Next.js 14.2.5

   Creating an optimized production build ...
 ✓ Compiled successfully
   Linting and checking validity of types ...
   Collecting page data ...
   Generating static pages (0/4) ...
   Generating static pages (1/4)
   Generating static pages (2/4)
   Generating static pages (3/4)
 ✓ Generating static pages (4/4)
   Finalizing page optimization ...
   Collecting build traces ...

Route (app)                              Size     First Load JS
┌ ○ /                                    142 B          87.2 kB
└ ○ /_not-found                          871 B          87.9 kB
+ First Load JS shared by all            87 kB
  ├ chunks/52d5e6ad-40eff88d15e66edb.js  53.6 kB
  ├ chunks/539-e1fa9689ed3badf0.js       31.5 kB
  └ other shared chunks (total)          1.84 kB

○  (Static)  prerendered as static content

The App container

Now we will add a “runner” container, that will use the build output from the Build container, and run next start:

// In the run() function:

const dockerAppContainer = new docker.Container(
  "Docker Container - App",
  {
    name: "app",
    image: dockerImageHetzner.imageName,
    volumes: [
      {
        volumeName: dockerVolumeAppBuild.name,
        containerPath: "/app/.next",
      },
    ],
    networksAdvanced: [
      { name: dockerNetworkPublic.id },
      { name: dockerNetworkInternal.id },
    ],
    command: ["pnpm", "start"],
    restart: "always",
  },
  { provider: dockerServerHetzner, dependsOn: [dockerAppBuildContainer] }
);

Deploy and verify that the app has started successfully:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Created     Docker Container - App docker:index:Container (1.1s)

✓  Complete

ssh root@116.203.183.180 -i ./id_ed25519_hetzner -o StrictHostKeyChecking=no -C "docker logs -f app"

> next-self-hosted@ start /app
> next start

  ▲ Next.js 14.2.5
  - Local:        http://localhost:3000

 ✓ Starting...
 ✓ Ready in 497ms

The app container might fail, because the build container has not finished building yet, but it will soon recover and function normally.

Add Cloudflare certificates

In order to upload files to the VPS, we need to install the Command provider and the Polumi package:

pnpm sst add @pulumi/command
pnpm add -D @pulumi/pulumi
pnpm install

Make sure that the /root/app and /root/app/certs directories exist on the VPS and upload Cloudflare Origin Server certificates:

// At the top of the file
import { asset as pulumiAsset } from "@pulumi/pulumi";

// In the run() function:

// Make sure that app directory exists
new command.remote.Command("Command - Ensure app directory", {
  create: "mkdir -p /root/app",
  connection: {
    host: server.ipv4Address,
    user: "root",
    privateKey: sshKeyLocal.privateKeyOpenssh,
  },
});

// Make sure that app/certs directory exists
new command.remote.Command("Command - Ensure app/certs directory", {
  create: "mkdir -p /root/app/certs",
  connection: {
    host: server.ipv4Address,
    user: "root",
    privateKey: sshKeyLocal.privateKeyOpenssh,
  },
});

// Copy Certificates to the VPS
new command.remote.CopyToRemote(
  "Copy - Certificates - Key",
  {
    source: new pulumiAsset.FileAsset(
      pathResolve("./certs/cloudflare.key.pem")
    ),
    remotePath: "/root/app/certs/cloudflare.key.pem",
    connection: {
      host: server.ipv4Address,
      user: "root",
      privateKey: sshKeyLocal.privateKeyOpenssh,
    },
  }
);
new command.remote.CopyToRemote(
  "Copy - Certificates - Cert",
  {
    source: new pulumiAsset.FileAsset(
      pathResolve("./certs/cloudflare.cert.pem")
    ),
    remotePath: "/root/app/certs/cloudflare.cert.pem",
    connection: {
      host: server.ipv4Address,
      user: "root",
      privateKey: sshKeyLocal.privateKeyOpenssh,
    },
  }
);
new command.remote.CopyToRemote(
  "Copy - Certificates - Authenticated Origin Pull",
  {
    source: new pulumiAsset.FileAsset(
      pathResolve("./certs/authenticated_origin_pull_ca.pem")
    ),
    remotePath: "/root/app/certs/authenticated_origin_pull_ca.pem",
    connection: {
      host: server.ipv4Address,
      user: "root",
      privateKey: sshKeyLocal.privateKeyOpenssh,
    },
  }
);

Start Nginx

Copy Nginx configuration file to the VPS and start the Nginx container:

// In the run() function:

// Copy Nginx config to the VPS
const commandCopyNginxConfig = new command.remote.CopyToRemote(
  "Copy - Nginx Config",
  {
    source: new pulumiAsset.FileAsset(
      pathResolve("./nginx/production.conf")
    ),
    remotePath: "/root/app/nginx.conf",
    connection: {
      host: server.ipv4Address,
      user: "root",
      privateKey: sshKeyLocal.privateKeyOpenssh,
    },
  }
);

// Run the Nginx container
const dockerNginxContainer = new docker.Container(
  "Docker Container - Nginx",
  {
    name: "app_container_nginx",
    image: "nginx:1.27.0-bookworm",
    volumes: [
      {
        hostPath: "/root/app/nginx.conf",
        containerPath: "/etc/nginx/nginx.conf",
      },
      {
        hostPath: "/root/app/certs",
        containerPath: "/certs",
      },
    ],
    command: ["nginx", "-g", "daemon off;"],
    networksAdvanced: [{ name: dockerNetworkPublic.id }],
    restart: "always",
    ports: [
      {
        external: 443,
        internal: 443,
      },
    ],
    healthcheck: {
      tests: ["CMD", "service", "nginx", "status"],
      interval: "30s",
      timeout: "5s",
      retries: 5,
      startPeriod: "10s",
    },
  },
  { provider: dockerServerHetzner, dependsOn: [dockerAppContainer] }
);

return { ip: server.ipv4Address };

Deploy and verify that the Nginx container is running:

pnpm sst deploy
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Deploy

|  Deleted     Docker Container - App Build docker:index:Container
|  Created     Command - Ensure app/certs directory command:remote:Command
|  Created     Command - Ensure app directory command:remote:Command
|  Created     Docker Container - App Build docker:index:Container
|  Created     Copy - Certificates - Cert command:remote:CopyToRemote (1.2s)
|  Created     Copy - Nginx Config command:remote:CopyToRemote (1.2s)
|  Created     Copy - Certificates - Key command:remote:CopyToRemote (1.2s)
|  Created     Copy - Certificates - Authenticated Origin Pull command:remote:CopyToRemote (1.2s)
|  Deleted     Docker Container - App docker:index:Container
|  Created     Docker Container - App docker:index:Container (1.2s)
|  Created     Docker Container - Nginx docker:index:Container (7.1s)

✓  Complete
   ip: 116.203.183.180

ssh root@116.203.183.180 -i ./id_ed25519_hetzner -o StrictHostKeyChecking=no -C "docker ps -a"

CONTAINER ID   IMAGE                                      COMMAND                  CREATED         STATUS                     PORTS                          NAMES
9c2cb18db304   nginx:1.27.0-bookworm                      "/docker-entrypoint.…"   3 minutes ago   Up 3 minutes (healthy)     80/tcp, 0.0.0.0:443->443/tcp   app_container_nginx
32e6a4cee8bc   next-self-hosted/next-self-hosted:latest   "docker-entrypoint.s…"   4 minutes ago   Up 3 minutes               3000/tcp                       app
f0c50aa32493   next-self-hosted/next-self-hosted:latest   "docker-entrypoint.s…"   4 minutes ago   Exited (0) 3 minutes ago                                  app_container_build

As you can see, Nginx and the application are running smoothly.

The final check

It’s time to make sure that the DNS record is pointing to the right IP address (yes, it is possible to add this to the SST config too, via the Cloudflare provider):

DNS settings – Cloudflare UI

Then, we can open the application and verify that it works:

The application in the browser

Congratulations! We have now completed out SST dive and can enjoy the freshly deployed application 👌

Cleaning up

SST makes it very easy to clean up – just run pnpm sst remove and the whole setup will go away:

pnpm sst remove
SST ❍ ion 0.1.90  ready!

➜  App:        next-self-hosted
   Stage:      antonprudkohliad

~  Remove

|  Deleted     Docker Container - Nginx docker:index:Container (1.9s)
|  Deleted     Docker Container - App docker:index:Container
|  Deleted     Docker Container - App Build docker:index:Container
|  Deleted     Docker Image - App - Hetzner docker:index:Image
|  Deleted     Docker Volume - App Build docker:index:Volume (2.1s)
|  Deleted     Docker Network - Public docker:index:Network (3.1s)
|  Deleted     Docker Network - Internal docker:index:Network (3.2s)
|  Deleted     Copy - Nginx Config command:remote:CopyToRemote
|  Deleted     Docker Server - Hetzner pulumi:providers:docker
|  Deleted     Copy - Certificates - Authenticated Origin Pull command:remote:CopyToRemote
|  Deleted     Command - Ensure app/certs directory command:remote:Command
|  Deleted     Copy - Certificates - Key command:remote:CopyToRemote
|  Deleted     Command - Ensure app directory command:remote:Command
|  Deleted     Copy - Certificates - Cert command:remote:CopyToRemote
|  Deleted     Server hcloud:index:Server (16.8s)
|  Deleted     SSH Key - Hetzner hcloud:index:SshKey
|  Deleted     SSH Key - Local tls:index:PrivateKey

✓  Removed

How to deploy a Next.js app to a VPS on Hetzner using Docker and GitHub Actions

Anton Prudkohliad — Fri, 26 Jul 2024 20:40:21 +0000

Deploying a Next.js app to a Virtual Private Server (VPS) on Hetzner can be a robust and cost-effective solution for hosting your application. This tutorial will guide you through the entire process, from writing a Dockerfile, to automating deployments using GitHub Actions. We'll also cover how to configure DNS and SSL certificates using Cloudflare. By the end, you'll have a fully automated deployment pipeline for your Next.js app running smoothly on a Hetzner VPS.

Before you begin

Install Docker
Create a GitHub account
Generate an SSH key
Add your SSH key to GitHub
Buy a domain – you can find a ~1€ one at Namecheap, just go to the “$2 or less” section. I got the next-self-hosted.click domain for this tutorial for just 1.07€
Create a Cloudflare account
Add your domain to Cloudflare
Create a Hetzner account
Create a new project
Add Next.js to your project

Additional files to ignore

Some files are just not meant to be stored in a version control system. Add the following to .gitignore to not bloat your repository:

# next.js
/.next/
/out/

# misc
.DS_Store
*.pem

# debug
yarn-debug.log*
yarn-error.log*

# local env files
.env*
!.env

Dockerfile

I find the original Next.js tutorial a little bit misguiding, because it tells you to copy the .env files into the Docker image and run the next build command during the Docker image build. This means that all your secrets (e.g. from the .env.production file, where you might have something like your database URL) might end up in the final image. Which is an equivalent of storing secrets in your GitHub repository and might pose a security risk.

Therefore, this image will not run the next build command and instead focus on installing dependencies. We will build the application later, in the production environment in a bootstrap container, a.k.a. Init Container. Please find the full Dockerfile below:

# The base image
FROM node:20.16.0-bookworm-slim AS base



# The "dependencies" stage
# It's good to install dependencies in a separate stage to be explicit about
# the files that make it into production stage to avoid image bloat
FROM base AS deps

# Enable Corepack so that Yarn can be installed
RUN corepack enable

# The application directory
WORKDIR /app

# Copy fiels for package management
COPY package.json yarn.lock .yarnrc.yml ./

# Install packages
RUN yarn install --immutable --inline-builds



# The final image
FROM base AS production

# Enable Corepack so that Yarn can be installed
RUN corepack enable

# Create a group and a non-root user to run the app
RUN groupadd --gid 1001 "nodejs"
RUN useradd --uid 1001 --create-home --shell /bin/bash --groups "nodejs" "nextjs"

# The application directory
WORKDIR /app

# Make sure that the .next directory exists
RUN mkdir -p /app/.next && chown -R nextjs:nodejs /app

# Copy packages from the dependencies stage
COPY --from=deps --chown=nextjs:nodejs /app/.yarn /app/.yarn

# Copy the rest of the application files
COPY --chown=nextjs:nodejs . .

# Enable production mode
ENV NODE_ENV=production

# Disable Next.js telemetry
ENV NEXT_TELEMETRY_DISABLED=1

# Configure application port
ENV PORT=3000

# Let image users know what port the app is going to listen on
EXPOSE 3000

# Change the user
USER nextjs:nodejs

# Make sure dependencies are picked up correctly
RUN yarn install --immutable --inline-builds

In order for Yarn to be able to copy it’s cache properly, let’s tell it to store the cache files in the local .yarn directory. Make sure that the .yarnrc.yml contains the following:

enableGlobalCache: false
enableTelemetry: false

To avoid the image bloat let’s also create a .dockerignore file. Copy everything from the .gitignore file and add the following:

# Dev tools
.git
.github
.editorconfig
.gitattributes
.node-version

# Docker files
.dockerignore*
Dockerfile*
docker-compose*.yml

# Readme
README.md

Test the Docker Image

Let’s test our Docker image. We will create two containers:

The “build” container app_build that will run the yarn build command, making sure that the Next.js application is built and stored in the .next directory The “runner” container app that will wait for the “build” container to complete successfuly, utilizing Docker healthcheck mechanism and then start the server using yarn start Both containers will be connected via a shared volume called app_build that will be mounted to the location of the .next directory.

Create a docker-compose.yml file:

services:
  # The main application service
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    volumes:
      - "app_build:/app/.next"
    ports:
      - "3000:3000"
    command: ["yarn", "start"]
    depends_on:
      app_build:
        condition: service_completed_successfully
  # The one-off container that builds the application
  app_build:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    volumes:
      - "app_build:/app/.next"
    command: ["yarn", "build"]
volumes:
  # The volume that is going to store the .next directory where the built
  # application is located
  app_build: {}

Now let’s start the app:

docker compose up --build app

Docker will build the image, run the app_build container first, wait for it to finish and then start the app container:

[+] Building 1.3s (26/26) FINISHED                                                                                                                                                               docker:desktop-linux
 => [app_build internal] load build definition from Dockerfile                                                                                                                                                   0.0s
 => => transferring dockerfile: 1.49kB                                                                                                                                                                           0.0s
 => [app_build internal] load .dockerignore                                                                                                                                                                      0.0s
 => => transferring context: 711B                                                                                                                                                                                0.0s
 => [app internal] load metadata for docker.io/library/node:20.16.0-bookworm-slim                                                                                                                                1.1s
 => [app base 1/1] FROM docker.io/library/node:20.16.0-bookworm-slim@sha256:a22f79e64de59efd3533828aecc9817bfdc1cd37dde598aa27d6065e7b1f0abc                                                                     0.0s
 => [app_build internal] load build context                                                                                                                                                                      0.0s
 => => transferring context: 236B                                                                                                                                                                                0.0s
 => CACHED [app deps 1/4] RUN corepack enable                                                                                                                                                                    0.0s
 => CACHED [app production 2/8] RUN groupadd --gid 1001 "nodejs"                                                                                                                                                 0.0s
 => CACHED [app production 3/8] RUN useradd --uid 1001 --create-home --shell /bin/bash --groups "nodejs" "nextjs"                                                                                                0.0s
 => CACHED [app production 4/8] WORKDIR /app                                                                                                                                                                     0.0s
 => CACHED [app production 5/8] RUN mkdir -p /app/.next && chown -R nextjs:nodejs /app                                                                                                                           0.0s
 => CACHED [app deps 2/4] WORKDIR /app                                                                                                                                                                           0.0s
 => CACHED [app_build deps 3/4] COPY package.json yarn.lock .yarnrc.yml ./                                                                                                                                       0.0s
 => CACHED [app_build deps 4/4] RUN yarn install --immutable --inline-builds                                                                                                                                     0.0s
 => CACHED [app_build production 6/8] COPY --from=deps --chown=nextjs:nodejs /app/.yarn /app/.yarn                                                                                                               0.0s
 => CACHED [app_build production 7/8] COPY --chown=nextjs:nodejs . .                                                                                                                                             0.0s
 => CACHED [app_build production 8/8] RUN yarn install --immutable --inline-builds                                                                                                                               0.0s
 => [app_build] exporting to image                                                                                                                                                                               0.0s
 => => exporting layers                                                                                                                                                                                          0.0s
 => => writing image sha256:1a4521137568e396fbdffe46689bbfaf5a118fba9f860f051c7526f9ed96b353                                                                                                                     0.0s
 => => naming to docker.io/library/next-self-hosted-app_build                                                                                                                                                    0.0s
 => [app internal] load .dockerignore                                                                                                                                                                            0.0s
 => => transferring context: 711B                                                                                                                                                                                0.0s
 => [app internal] load build definition from Dockerfile                                                                                                                                                         0.0s
 => => transferring dockerfile: 1.49kB                                                                                                                                                                           0.0s
 => [app internal] load build context                                                                                                                                                                            0.0s
 => => transferring context: 236B                                                                                                                                                                                0.0s
 => CACHED [app deps 3/4] COPY package.json yarn.lock .yarnrc.yml ./                                                                                                                                             0.0s
 => CACHED [app deps 4/4] RUN yarn install --immutable --inline-builds                                                                                                                                           0.0s
 => CACHED [app production 6/8] COPY --from=deps --chown=nextjs:nodejs /app/.yarn /app/.yarn                                                                                                                     0.0s
 => CACHED [app production 7/8] COPY --chown=nextjs:nodejs . .                                                                                                                                                   0.0s
 => CACHED [app production 8/8] RUN yarn install --immutable --inline-builds                                                                                                                                     0.0s
 => [app] exporting to image                                                                                                                                                                                     0.0s
 => => exporting layers                                                                                                                                                                                          0.0s
 => => writing image sha256:8bdd829336f1ddb87571955f221e76da1fab9cf1e98ad921fc2625f82eb65d88                                                                                                                     0.0s
 => => naming to docker.io/library/next-self-hosted-app                                                                                                                                                          0.0s
[+] Running 1/0
 ✔ Container next-self-hosted-app_build-1  Created                                                                                                                                                               0.0s
Attaching to next-self-hosted-app-1, next-self-hosted-app_build-1
next-self-hosted-app_build-1  |   ▲ Next.js 14.2.5
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |    Creating an optimized production build ...
next-self-hosted-app_build-1  |  ✓ Compiled successfully
next-self-hosted-app_build-1  |    Linting and checking validity of types ...
next-self-hosted-app_build-1  |    Collecting page data ...
next-self-hosted-app_build-1  |    Generating static pages (0/4) ...
next-self-hosted-app_build-1  |    Generating static pages (1/4)
next-self-hosted-app_build-1  |    Generating static pages (2/4)
next-self-hosted-app_build-1  |    Generating static pages (3/4)
next-self-hosted-app_build-1  |  ✓ Generating static pages (4/4)
next-self-hosted-app_build-1  |    Finalizing page optimization ...
next-self-hosted-app_build-1  |    Collecting build traces ...
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  | Route (app)                              Size     First Load JS
next-self-hosted-app_build-1  | ┌ ○ /                                    142 B          87.1 kB
next-self-hosted-app_build-1  | └ ○ /_not-found                          872 B          87.9 kB
next-self-hosted-app_build-1  | + First Load JS shared by all            87 kB
next-self-hosted-app_build-1  |   ├ chunks/354-67999519566e6594.js       31.5 kB
next-self-hosted-app_build-1  |   ├ chunks/41f0bf82-88862f34f87ffcaf.js  53.6 kB
next-self-hosted-app_build-1  |   └ other shared chunks (total)          1.84 kB
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  | ○  (Static)  prerendered as static content
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1  |
next-self-hosted-app_build-1 exited with code 0
next-self-hosted-app-1        |   ▲ Next.js 14.2.5
next-self-hosted-app-1        |   - Local:        http://localhost:3000
next-self-hosted-app-1        |
next-self-hosted-app-1        |
next-self-hosted-app-1        |  ✓ Starting...
next-self-hosted-app-1        |  ✓ Ready in 181ms

You then will be able to see the running app:

The app running locally

Production Docker Compose File

We will be running the production application using Docker Compose as well. It is going to use the same runner+build container combination as in docker-compose.yml. The main difference is that there also will be a reverse proxy container that will stand between the Internet and the application.

Create a docker-compose.production.yml file:

services:
  # The reverse proxy - the main entrypoint into the application. Holds the TLS
  # certificates.
  nginx:
    image: "nginx:1.27.0-bookworm"
    volumes:
      - ./nginx/production.conf:/etc/nginx/nginx.conf
    command: ["nginx", "-g", "daemon off;"]
    restart: always
    ports:
      - 80:80
    networks:
      - public
    depends_on:
      app:
        condition: service_started
    healthcheck:
      test: ["CMD", "service", "nginx", "status"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 10s
      start_interval: 1s
  # The main application service
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    env_file:
      - .env.production
    volumes:
      - "app_build:/app/.next"
    command: ["yarn", "start"]
    restart: always
    networks:
      - public
      - internal
    depends_on:
      app_build:
        condition: service_completed_successfully
  # The one-off container that builds the application
  app_build:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    env_file:
      - .env.production
    volumes:
      - "app_build:/app/.next"
    command: ["yarn", "build"]
volumes:
  # The volume that is going to store the .next directory where the built
  # application is located
  app_build: {}
networks:
  # The network for services to which NGINX is connected, meant for services
  # that have to be exposed to the outside (e.g. the Next.js application or an
  # API server).
  public: {}
  # The network for services that are not meant to be exposed to the outside
  # e.g. Postgres database, Redis cache.
  internal: {}

We will also create a custom NGINX config file nginx/production.conf that will forward all traffic from port 80 on the host to port 3000 in the Next.js app:

user nginx;
pid /var/run/nginx.pid;
worker_processes auto;
events {
  worker_connections 1024;
}

http {
  log_format json_combined escape=json
    '{'
      '"request_id":"$request_id",'
      '"host":"$host",'
      '"time":"$time_iso8601",'
      '"x_forwarded_for":"$http_x_forwarded_for",'
      '"remote_addr":"$remote_addr",'
      '"remote_user":"$remote_user",'
      '"request":"$request",'
      '"status": "$status",'
      '"body_bytes_sent":"$body_bytes_sent",'
      '"http_referrer":"$http_referer",'
      '"http_user_agent":"$http_user_agent",'
      '"request_time":"$request_time"'
    '}';

  access_log /var/log/nginx/access.log json_combined;
  error_log  /var/log/nginx/error.log warn;

  include /etc/nginx/mime.types;
  default_type application/octet-stream;
  sendfile on;
  keepalive_timeout 65;

  proxy_set_header X-Request-Id $request_id;

  add_header X-Request-Id $request_id;
  add_header X-Request-Time $request_time;

  server {
    listen 80;

    location / {
      client_max_body_size 1M;

      proxy_pass http://app:3000;
    }
  }
}

We don’t need the nginx directory in the application Docker image, so let’s add it to the .dockerignore file:

# Nginx config
nginx

Push your code to GitHub

Create a new GitHub repository:

GitHub UI – creating a new repository

Add it as a new remote to your local one (git@github.com:prutya/next-self-hosted.git will be different for you, of course):

git remote add origin git@github.com:prutya/next-self-hosted.git

Push the changes:

git push origin main

Check that the repository has been updated:

GitHub UI – the repository

Now we need some server to run the app.

Buy a VPS

Create a new project on Hetzner:

Hetzner UI – adding a new project

Add a new server to the project:

Hetzner UI – adding a new server

Select "Docker CE" as the Image:

Hetzner UI – server image selection

Select the CX22 Type for the node:

Hetzner UI – server type selection

Add your public SSH key so that you can ssh into the VPS:

Hetzner UI – adding an SSH key

Finalize the setup by clicking “Create & Buy now”

Hetzner UI – the final step of server creation

This will create a new server on Hetzner.

Generate an SSH Key for the VPS

Connect to the VPS (your VPS IP address will be different):

ssh root@5.75.157.116

The authenticity of host '5.75.157.116 (5.75.157.116)' can't be established.
ED25519 key fingerprint is SHA256:oaPM2CQ4J0a4626sy/0jksB2eNhNBg2fA0pYwFASW7w.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '5.75.157.116' (ED25519) to the list of known hosts.
Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.8.0-38-generic x86_64)
...
root@next-self-hosted:~#

Generate a new SSH key that will identify the VPS:

ssh-keygen -t ed25519 -C ""

Generating public/private ed25519 key pair.
Enter file in which to save the key (/root/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_ed25519
Your public key has been saved in /root/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:V2Z6KJMoEMH3yBS9XlV3TYKkwiD4hYr5gJR/S5P9N74
The key's randomart image is:
+--[ED25519 256]--+
| .+oo+.    oo.o.+|
| oo.+.oo  .... o.|
|ooo* +o.o.. +    |
|= .o+=oo.o *     |
| o  +.+.S + .    |
|  .  o.  = +     |
|          o .    |
|           .     |
|           E.    |
+----[SHA256]-----+

cat /root/.ssh/id_ed25519.pub

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPUfdcXNykmjIU9BGBKk/GLEL27srCtbJPPSDETqkQMV

Add the public part to the list of Deploy keys in the GitHub repository:

GitHub UI – adding a Deploy key

With this configurations in place, the VPS should be able to pull changes from the GitHub repository.

Pull your code to the VPS

Now the VPS should be able to clone the repository:

git clone git@github.com:prutya/next-self-hosted.git

Cloning into 'next-self-hosted'...
The authenticity of host 'github.com (140.82.121.3)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
remote: Enumerating objects: 37, done.
remote: Counting objects: 100% (37/37), done.
remote: Compressing objects: 100% (18/18), done.
remote: Total 37 (delta 15), reused 37 (delta 15), pack-reused 0
Receiving objects: 100% (37/37), 8.31 KiB | 4.16 MiB/s, done.
Resolving deltas: 100% (15/15), done.

Verify by changing into the repo directory and listing the files:

cd next-self-hosted
ls -la

total 76
drwxr-xr-x 5 root root 4096 Jul 26 06:30 .
drwx------ 5 root root 4096 Jul 26 06:30 ..
drwxr-xr-x 2 root root 4096 Jul 26 06:30 app
-rw-r--r-- 1 root root 1696 Jul 26 06:30 docker-compose.production.yml
-rw-r--r-- 1 root root  671 Jul 26 06:30 docker-compose.yml
-rw-r--r-- 1 root root 1450 Jul 26 06:30 Dockerfile
-rw-r--r-- 1 root root  650 Jul 26 06:30 .dockerignore
-rw-r--r-- 1 root root  134 Jul 26 06:30 .editorconfig
drwxr-xr-x 8 root root 4096 Jul 26 06:30 .git
-rw-r--r-- 1 root root  142 Jul 26 06:30 .gitattributes
-rw-r--r-- 1 root root  476 Jul 26 06:30 .gitignore
drwxr-xr-x 2 root root 4096 Jul 26 06:30 nginx
-rw-r--r-- 1 root root    8 Jul 26 06:30 .node-version
-rw-r--r-- 1 root root  310 Jul 26 06:30 package.json
-rw-r--r-- 1 root root   19 Jul 26 06:30 README.md
-rw-r--r-- 1 root root 9894 Jul 26 06:30 yarn.lock
-rw-r--r-- 1 root root   48 Jul 26 06:30 .yarnrc.yml

Create .env.production for storing the secrets:

touch .env.production

The app is now ready to be started.

Start the app

Just like we did locally, let's start the app via compose CLI, this time we will use a different compose file though and we will run it in the background by using --detach:

docker compose --file docker-compose.production.yml up --build --detach nginx

Navigate to the IP address of your VPS in browser:

The application running on VPS accessed via IP address

Great, now let’s set configure our domain to point to the VPS.

Configure DNS

Let’s add a new DNS record for the domain. There needs to be an A record pointing to the IP address of the VPS.

Cloudflare UI – creating an A record for the domain

Once updated, navigate to the domain to see that we can now access the app this way too:

The application running on VPS accessed via domain name

However, the application is currently not secure. It is running on port 80 via plain HTTP protocol without encryption. This might be an issue if you want to process user data, because it will be vulnerable for MITM attacks.

Configure TLS (SSL)

In order for the app to use HTTPS, we will generate Origin Server certificates, add them to the VPS and update Cloudflare settings enabling the “Full (strict)” TLS mode. We will also enable the “Always Use HTTPS” setting and change the minimum allowed TLS version to v1.2.

Let’s go to the SSL/TLS → Origin Server section and create a new ECC certificate:

Cloudflare UI – generating a new Origin Server certificate

Cloudflare will generate the certificates and open the download page where you can copy the certificates:

Cloudflare UI – a new Origin Server certificate

Let’s store the private part in certs/cloudflare.key.pem and the public one in certs/cloudflare.cert.pem files:

File structure showing certificates location

Add the certs directory to .gitignore and .dockerignore files so that we don’t push them to the repository and don’t add them to the Docker image:

# Certificates
certs

Create a certs directory on the VPS and copy the certificates there:

ssh root@5.75.157.116 -C "mkdir -p /root/next-self-hosted/certs"

scp ./certs/cloudflare.key.pem root@5.75.157.116:/root/next-self-hosted/certs
cloudflare.key.pem    100%  241     6.6KB/s   00:00

scp ./certs/cloudflare.cert.pem root@5.75.157.116:/root/next-self-hosted/certs
cloudflare.cert.pem    100% 1176    33.2KB/s   00:00

ssh root@5.75.157.116 -C "ls -la /root/next-self-hosted/certs"
total 16
drwxr-xr-x 2 root root 4096 Jul 26 07:05 .
drwxr-xr-x 6 root root 4096 Jul 26 07:05 ..
-rw-r--r-- 1 root root 1176 Jul 26 07:05 cloudflare.cert.pem
-rw-r--r-- 1 root root  241 Jul 26 07:05 cloudflare.key.pem

Adjust the NGINX config server section to listen on port 443 instead of 80 and point it to the certificates:

server {
  listen 443 ssl;
  listen [::]:443 ssl;

  http2 on;

  ssl_session_cache    shared:SSL:1m;
  ssl_session_timeout  5m;

  ssl_ciphers  HIGH:!aNULL:!MD5;
  ssl_prefer_server_ciphers  on;

  ssl_certificate /certs/cloudflare.cert.pem;
  ssl_certificate_key /certs/cloudflare.key.pem;

  location / {
    client_max_body_size 1M;

    proxy_pass http://app:3000;
  }
}

Adjust the docker-compose.production.yml so that the certs directory is mounted into the nginx container and the port 443 is exposed instead of 80:

nginx:
  image: "nginx:1.27.0-bookworm"
  volumes:
    - ./nginx/production.conf:/etc/nginx/nginx.conf
    - ./certs:/certs # Add certificates volume
  command: ["nginx", "-g", "daemon off;"]
  restart: always
  ports:
    - 443:443 # Expose port 443 instead of 80
  networks:
    - public
  depends_on:
    app:
      condition: service_started
  healthcheck:
    test: ["CMD", "service", "nginx", "status"]
    interval: 30s
    timeout: 5s
    retries: 5
    start_period: 10s
    start_interval: 1s

Push the changes to the GitHub repo:

git add -A
git commit -m "Configure TLS"
git push origin main

Stop the app on the VPS:

docker compose --file docker-compose.production.yml down -t 1

[+] Running 6/6
 ✔ Container next-self-hosted-nginx-1      Removed                                                                                                                                                               0.2s
 ✔ Container next-self-hosted-app-1        Removed                                                                                                                                                               0.2s
 ✔ Container next-self-hosted-app_build-1  Removed                                                                                                                                                               0.0s
 ✔ Network next-self-hosted_internal       Removed                                                                                                                                                               0.2s
 ✔ Network next-self-hosted_public         Removed                                                                                                                                                               0.1s
 ✔ Network next-self-hosted_default        Removed

Pull the changes on the VPS:

git pull origin main

Start the app again:

docker compose --file docker-compose.production.yml up --build --detach nginx

[+] Running 6/6
 ✔ Network next-self-hosted_default        Created                                                                                                                                                               0.1s
 ✔ Network next-self-hosted_public         Created                                                                                                                                                               0.1s
 ✔ Network next-self-hosted_internal       Created                                                                                                                                                               0.1s
 ✔ Container next-self-hosted-app_build-1  Exited                                                                                                                                                               23.9s
 ✔ Container next-self-hosted-app-1        Started                                                                                                                                                              24.2s
 ✔ Container next-self-hosted-nginx-1      Started

Turn on Full (strict) TLS mode on Cloudflare:

Cloudflare UI – enabling Full (strict) mode

Now if we try to access port 80 on the server it will return an error:

➜  next-self-hosted git:(main) curl -v http://next-self-hosted.click/
*   Trying 104.21.21.27:80...
* Connected to next-self-hosted.click (104.21.21.27) port 80 (#0)
> GET / HTTP/1.1
> Host: next-self-hosted.click
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/1.1 521
< Date: Fri, 26 Jul 2024 07:15:11 GMT
< Content-Type: text/plain; charset=UTF-8
< Content-Length: 15
< Connection: keep-alive
< Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v4?s=HevjuWN3sWeCpjOrLz9QnK6IVXPTNOirKR5Hvli5V0V5CiS60meW1uOdDTBzt%2BxadT92KEW%2FOXuc9wBVZXnpADy6fVRoNSVsEF4Zg%2Bx3J61qDJVPbtY%2Bu9EsPkLwfstemCcYbFYlspBz"}],"group":"cf-nel","max_age":604800}
< NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
< X-Frame-Options: SAMEORIGIN
< Referrer-Policy: same-origin
< Cache-Control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
< Expires: Thu, 01 Jan 1970 00:00:01 GMT
< Server: cloudflare
< CF-RAY: 8a9298deb8f6c31b-VIE
< alt-svc: h3=":443"; ma=86400
<
* Connection #0 to host next-self-hosted.click left intact
error code: 521%

Let’s handle that error a bit more gracefully. Enable the “Always use HTTPS” toggle in the SSL/TLS → Edge Certificates section on Cloudflare:

Cloudflare UI – enabling the Always Use HTTPS toggle

While we are here, we can also set the Minimum TLS Version to v1.2:

Cloudflare UI – changing the Minimum TLS Version to v1.2

Now if we try to access the port 80, Cloudflare will respond with code 301 Moved Permanently redirecting the user to the HTTPS port:

➜  next-self-hosted git:(main) curl -v http://next-self-hosted.click/
*   Trying 172.67.196.4:80...
* Connected to next-self-hosted.click (172.67.196.4) port 80 (#0)
> GET / HTTP/1.1
> Host: next-self-hosted.click
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Date: Fri, 26 Jul 2024 07:17:36 GMT
< Content-Type: text/html
< Content-Length: 167
< Connection: keep-alive
< Cache-Control: max-age=3600
< Expires: Fri, 26 Jul 2024 08:17:36 GMT
< Location: https://next-self-hosted.click/
< Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v4?s=FYFTNzALCb2tM6jP%2F79nGLE%2FpoztnjDmbmgeoZEaKofvmIExP3aX346OJuB90Tdiem5Q5wKRe%2FDKscdnfkXAqbtxHNKtMVNtlU2YH2%2B5103Dsn9SFnE5%2FHd%2FJfsWrhsya%2B8UXzoruUWo"}],"group":"cf-nel","max_age":604800}
< NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
< Server: cloudflare
< CF-RAY: 8a929c690ac5c2b6-VIE
< alt-svc: h3=":443"; ma=86400
<
<html>
<head><title>301 Moved Permanently</title></head>
<body>
<center><h1>301 Moved Permanently</h1></center>
<hr><center>cloudflare</center>
</body>
</html>
* Connection #0 to host next-self-hosted.click left intact

We can now verify the app and see that it’s secure:

The application secure connection

Let us now automate the process of deployment so that we don’t have to ssh in the VPS, pull the changes from GitHub and restart the app manually.

Automated deployment via GitHub Actions

We are going to generate an SSH key for GitHub Actions. The private key will be stored as Base64 in GitHub secrets, and the public one will be added to the list of authorized_hosts on the VPS. GitHub Actions will read the private key from the secret and use it to connect to the VPS to pull the recent changes and restart the app.

Generate an SSH key for GitHub, provide the ./id_ed25519_github as the name of the file to save the key:

ssh-keygen -t ed25519 -C ""

Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/anton/.ssh/id_ed25519): ./id_ed25519_github
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ./id_ed25519_github
Your public key has been saved in ./id_ed25519_github.pub
The key fingerprint is:
SHA256:Awbwkyfcl4PediRceHSUE/ufnbk0lk+b+hl20u/OIW8
The key's randomart image is:
+--[ED25519 256]--+
|  ...    oo.+o   |
|   o + o.o..o.   |
|    * * *.. ..   |
|     * + +   .   |
|      . S .   .  |
|       . o     o*|
|             ..%*|
|              *E%|
|             .+X*|
+----[SHA256]-----+

The private part will be stored in ./id_ed25519_github and the public – in ./id_ed25519_github.pub.

Encode the private part as Base64 and copy it to the clipboard:

cat id_ed25519_github | base64 | pbcopy

Store it in GitHub Actions secret VPS_SSH_KEY:

GitHub UI - adding the VPS_SSH_KEY secret

Add the public part to VPS authorized_keys file:

ssh root@5.75.157.116 -C "echo \"$(cat id_ed25519_github.pub)\" >> ~/.ssh/authorized_keys"

Verify the connection as if you were GitHub:

ssh -i id_ed25519_github root@5.75.157.116

Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.8.0-38-generic x86_64)
...
root@next-self-hosted:~#

Delete the GitHub keys from your machine - you no longer need them:

rm id_ed25519_github*

We are also going to need to add the VPS public keys to known_hosts of the SSH client in GitHub Actions.

ssh-keyscan 5.75.157.116 | base64 | pbcopy
# 5.75.157.116:22 SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.4
# 5.75.157.116:22 SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.4
# 5.75.157.116:22 SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.4
# 5.75.157.116:22 SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.4
# 5.75.157.116:22 SSH-2.0-OpenSSH_9.6p1 Ubuntu-3ubuntu13.4

Paste the public keys in GitHub Actions secret VPS_SSH_HOST_KEYS:

GitHub UI - adding the VPS_SSH_HOST_KEYS secret

Add VPS user name (root) as VPS_SSH_USERNAME secret:

GitHub UI - adding the VPS_SSH_USERNAME secret

Add VPS IP address as VPS_IP secret:

GitHub UI - adding the VPS_IP secret

Create a script that will be triggered by GitHub Actions runner – scripts/production.sh:

#!/usr/bin/env bash

set -exo pipefail

# Build and run the latest version of the app
docker compose --file docker-compose.production.yml up --build --detach nginx

# Remove the unused containers
docker system prune --force

Make it executable:

chmod +x scripts/production.sh

Add the GitHub action .github/workflows/push-to-main.yml that decodes the SSH key for accessing the VPS and start the scripts/production.sh script in the background:

name: Push to main
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      # Clone the repo
      - name: Checkout
        uses: actions/checkout@v4
      - name: Prepare SSH key
        run: |
          echo "${{ secrets.VPS_SSH_KEY }}" | base64 -d > vps_key.pem
          chmod 0600 vps_key.pem
      - name: Prepare the known_hosts
        run: |
          mkdir ~/.ssh/ && touch ~/.ssh/known_hosts
          echo "${{ secrets.VPS_SSH_HOST_KEYS }}" | base64 -d >> ~/.ssh/known_hosts
      - name: Start the deployment of the latest version in the background
        run: |
          DATE=$(date "+%Y%m%d%H%M%S")

          ssh -i vps_key.pem "${{ secrets.VPS_SSH_USERNAME }}@${{ secrets.VPS_IP }}" bash -c "'
            set -eo pipefail

            cd app
            git pull origin main

            nohup ./production.sh > "deploy-${DATE}.log" 2> "deploy-${DATE}.log" &
          '"

Push the changes and check GitHub Actions:

GitHub UI – deployment Action log

Verify the deployment on the VPS – you can check the deploy-.log file to see how it went:

ls -al
...
-rw-r--r-- 1 root root 5137 Jul 26 07:56 deploy-20240726075540.log
...

Verify that the docker container is running:

docker ps -a

CONTAINER ID   IMAGE                   COMMAND                  CREATED              STATUS                        PORTS                                           NAMES
1d0cd6f89119   nginx:1.27.0-bookworm   "/docker-entrypoint.…"   About a minute ago   Up About a minute (healthy)   80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp   next-self-hosted-nginx-1
5db52edde339   next-self-hosted-app    "docker-entrypoint.s…"   About a minute ago   Up About a minute             3000/tcp                                        next-self-hosted-app-1

Test the automated deployment

Let’s change the text on the main page (app/page.js) and push a new commit:

export default function Page() {
  return <h1>Hello, Blog!</h1>;
}

Push the changes:

git add app
git commit -m "Update page text"
git push origin main

After some time, the changes should make it to the live app:

Updated main page of the application

That’s it! This should give a decent start into running your own instance of Next.js.

If you want to further secure you deployment, please see the “Bonus” sections 😉

Bonus: Set up Firewall on Hetzner

In order to restrict access to the ports that are not required to run the app, we can configure a firewall on Hetzner.

Open the Firewalls section in the project:

Hetzner UI – Firewalls section

Create new Firewall only allowing TCP traffic on port 22 and 443:

Hetzner UI – creating a new Firewall

Make sure to apply it to the Server:

Hetzner UI – applying the Firewall to the Server

Done. Any other ports will no longer be accessible from outside the VPS.

Bonus: Set up Authenticated Origin Pulls (mTLS)

In order to only allow Cloudflare to connect to port 443, we can configure Authenticated Origin Pulls, also know as mutual TLS.

Download the Cloudflare certificate to the certs directory:

curl -o certs/authenticated_origin_pull_ca.pem https://developers.cloudflare.com/ssl/static/authenticated_origin_pull_ca.pem

Copy it to the VPS:

scp ./certs/authenticated_origin_pull_ca.pem root@5.75.157.116:/root/next-self-hosted/certs/authenticated_origin_pull_ca.pem

Configure NGINX server block:

ssl_verify_client on;
ssl_client_certificate /etc/nginx/certs/authenticated_origin_pull_ca.pem;

Enable Authenticated Origin Pulls in Cloudflare settings:

Cloudflare UI – enabling Authenticated Origin Pulls

After the changes are pushed, verify that the app is still working:

The main page of the application

That’s it, now only Cloudflare will be able to access your Origin Server.

How to set up a new project using Yarn in 2024

Anton Prudkohliad — Sat, 11 May 2024 10:20:13 +0000

Let’s see how we could set up a shiny new JavaScript project using the Yarn package manager. We are going to set up nodenv, install Node.js and Yarn, and then initialize a new project that we will then be able to use as a foundation for our further ideas.

Setting up nodenv

First, we are going to need Node.js. I use nodenv to manage multiple Node.js installations on my machine. The easiest way to install it on a Mac is to use Homebrew (check their Installation documentation if you’re on a different platform):

brew install nodenv

After that, add the following line to the bottom of your .zshrc or .bashrc file (for me it is located in the home directory, a.k.a. ~):

# ~/.zshrc

# ...

eval "$(nodenv init -)"

From now on, every time you run node, nodenv will automatically pick the Node.js version specified in a .node-version file.

Setting up Node

Now, let’s create our project directory and add the latest Long Term Support version of Node.js (at the moment of writing it’s 20.13.1, check the Node.js website if you’re not sure) to the .node-version file:

# Create the project directory
mkdir project

# Change into it
cd project

# Tell nodenv to use Node 20.13.1 in your project's directory
echo "20.13.1" > .node-version

To smoke-test the installation, run:

node --version

If there’s no such Node installation on your machine (which was the case for me), you’ll see an output similar to this:

nodenv: version `20.13.1' is not installed (set by /Users/anton/project/.node-version)

To fix that, use nodenv to install the Node version specified in the .node-version file:

nodenv install $(cat .node-version)

If it fails to install this version, make sure that your node-build is up-to-date and try again:

brew update && brew upgrade node-build

nodenv install $(cat .node-version)

Nodenv will download and install Node:

Downloading node-v20.13.1-darwin-arm64.tar.gz...
-> https://nodejs.org/dist/v20.13.1/node-v20.13.1-darwin-arm64.tar.gz
Installing node-v20.13.1-darwin-arm64...
Installed node-v20.13.1-darwin-arm64 to /Users/anton/.nodenv/versions/20.13.1

Now our little smoke-test should return the correct version:

node --version
# => v20.13.1

Setting up Yarn

Yarn is a package manager — a tool that allows you to use code from other developers. According to Yarn installation documentation, the preferred way to install Yarn is to use Corepack - a built-in tool for “managing versions of your package managers”. Let’s enable Corepack and install the stable version of Yarn:

# Enable Corepack
corepack enable

# Install Yarn
corepack prepare yarn@stable --activate

Run a smoke-test to see if the installation was successful. The following command should return a version, for me it was 4.2.2:

yarn --version
# => 4.2.2

Setting up the project

Now that we have our package manager in place, let’s use it to initialize the project:

yarn init

The command above will create several configuration files and initialize a git repository in our project folder, here’s what some of them are for:

.editorconfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. Find more information on the EditorConfig website if you’re curious.
.gitattributes helps git manage your project files better. See more information on the git website.
.gitignore specifies which files are not supposed to be tracked by git. See more information here.
package.json contains information about the package, such as name, packageManager, and so on.
README.md is a Markdown file where you can write some documentation.
yarn.lock helps Yarn get consistent installs of dependencies (packages) across different machines. Find more in yarn.lock documentation.

Also, the command might tell you that there is a new version of Yarn available:

➤ YN0088: A new stable version of Yarn is available: 4.2.2!
➤ YN0088: Upgrade now by running yarn set version 4.2.2

➤ YN0000: · Yarn 4.1.1
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed
➤ YN0000: · Done in 0s 23ms

So, just for the sake keeping stuff as up-to-date as possible, set the Yarn’s version to the suggested one:

yarn set version 4.2.2

Finalize the setup by running yarn install or just yarn:

yarn

➤ YN0000: · Yarn 4.2.2
➤ YN0000: ┌ Resolution step
➤ YN0000: └ Completed
➤ YN0000: ┌ Fetch step
➤ YN0000: └ Completed
➤ YN0000: ┌ Link step
➤ YN0000: └ Completed
➤ YN0000: · Done in 0s 25ms

Project smoke test

Let’s make sure that we can packages and run code. We will install lodash, call a function from it, and print the output.

Install lodash:

yarn add lodash

Create an index.js file with the following content:

// index.js

const now = require("lodash/now");

console.log(now());

Run the index.js, it will print the current timestamp:

yarn node index.js

# => 1715420455747

That’s it! Now you can use this setup as a solid foundation for your future app.

Feedback

You can find the source code here:

prutya / tutorial-project-setup-yarn-202405011

How to set up a new project using Yarn in 2024

06_project_setup_yarn_20240511

View on GitHub

If you have any feedback, please feel free to submit an Issue.

My original blog post

How to implement a Multi-Select Dropdown component with React and Tailwind CSS

Anton Prudkohliad — Wed, 08 May 2024 16:30:18 +0000

The end result will look like this:

The Multi-Select Dropdown

Prerequisites

I’ll skip the boring part such as setting up the project and adding Tailwind CSS to it. Instead, please use the following links as a reference:

I also created a GitHub repository, you can follow from this commit.

The design

The design of the Multi-Select Dropdown component

As you can see from the image, there are two main parts of the component: the “toggle” (the panel where it says “11 selected”) and the dropdown part with the list of options.

The skeleton

First, create the component in the src/components directory:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown() {
  return (
    <label className="relative">
      <input type="checkbox" className="hidden peer" />

      <div className="cursor-pointer after:content-['▼'] after:text-xs after:ml-1">
        {"Show the dropdown"}
      </div>

      <div className="hidden peer-checked:flex absolute bg-white border">
        {"Welcome to the dropdown"}
      </div>
    </label>
  );
}

I also added a triangle after the “Show the dropdown” text to indicate that this is indeed a dropdown 🙌.

Next, create a page, so that there is a place to display the component:

// src/app/page.js

import MultiSelectDropdown from "../components/MultiSelectDropdown";

export default function Page() {
  return (
    <>
      <h1>{"Multi-Select Dropdown"}</h1>
      <form>
        <MultiSelectDropdown />
        <input type="submit" />
      </form>
    </>
  );
}

This is what the result so far should look like:

Initial markup behavior recording

Smooth transitions

This is an optional step 💅. I just added some animations to the dropdown:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown() {
  return (
    <label className="relative">
      <input type="checkbox" className="hidden peer" />

      <div className="cursor-pointer after:content-['▼'] after:text-xs after:ml-1 after:inline-flex after:items-center peer-checked:after:-rotate-180 after:transition-transform">
        {"Show the dropdown"}
      </div>

      <div className="absolute bg-white border p-2 transition-opacity opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto">
        {"Welcome to the dropdown"}
      </div>
    </label>
  );
}

What it looks like with smooth transitions:

Smooth transitions added

Rendering the options

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown({ formFieldName, options }) {
    // ...
}

Now, let’s render each option as a label with an input of type checkbox instead of the {"Welcome to the dropdown"} part:

// src/components/MultiSelectDropdown.jsx

export default function MultiSelectDropdown({ formFieldName, options }) {
  return (
    <label className="relative">
      <input type="checkbox" className="hidden peer" />
        {"Show the dropdown"}
      </div>

      <div className="absolute bg-white border transition-opacity opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto">
        <ul>
          {options.map((option, i) => {
            return (
              <li key={option}>
                <label className="flex whitespace-nowrap cursor-pointer px-2 py-1 transition-colors hover:bg-blue-100 [&:has(input:checked)]:bg-blue-200">
                  <input
                    type="checkbox"
                    name={formFieldName}
                    value={option}
                    className="cursor-pointer"
                  />
                  <span className="ml-1">{option}</span>
                </label>
              </li>
            );
          })}
        </ul>
      </div>
    </label>
  );

And let’s also pass the actual options and form field name to the component instance (we are going to use a list of totally randomly selected countries):

// src/app/page.js

const COUNTRIES = [ "Austria", "Belgium", "Croatia", "Bulgaria", "Cyprus", "Czech Republic", "Denmark", "Estonia", "Finland", "France", "Germany", "Greece", "Hungary", "Ireland", "Italy", "Latvia", "Lithuania", "Luxembourg", "Malta", "Netherlands", "Poland", "Portugal", "Romania", "Slovakia", "Slovenia", "Spain", "Sweden", "Ukraine"];

export default function Page() {
  return (
    <>
      <h1>{"Multi-Select Dropdown"}</h1>
      <form>
        <MultiSelectDropdown formFieldName={"countries"} options={COUNTRIES} />
        <input type="submit" />
      </form>
    </>
  );
}

Now we finally can see the list of the options in the dropdown:

Dropdown with options

Testing the form submission

To do that, we will create another folder in the src/app directory called api and then create a route.js file inside.

In this file we are going to export an async function called POST that will read the form data from the request, getAll the countries from the form data, and print them out:

// src/app/api/route.js 

export async function POST(request) {
  const formData = await request.formData();
  const countries = formData.getAll("countries");

  console.debug("countries", countries);

  return new Response("All good", { status: 200 });
}

We also need to make sure that the form is submitted to this endpoint, so let’s add action="/api" and method="post" to our form tag:

// src/app/page.js

// ...

export default function Page() {
  return (
    <>
      <h1>{"Multi-Select Dropdown"}</h1>
      <form action="/api" method="post">
        <MultiSelectDropdown formFieldName={"countries"} options={COUNTRIES} />
        <input type="submit" />
      </form>
    </>
  );
}

Now, when you go to the dropdown, select a couple of countries, and click “Submit”, you should be able to see the list of the countries that you have selected in the server logs:

Server logs with the list of selected countries

Handling changes

Since onChange is an event handler and we are using Next.js with all the SSR and SSG quirks, we are also going to need to add a "use client" directive at the top.

We are also going to need the selectedOptions state to keep track of what the user has already selected:

// src/components/MultiSelectDropdown.jsx

"use client";

import { useState } from "react";

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange,
}) {
  const [selectedOptions, setSelectedOptions] = useState([]);

  // ...
}

Then, every time any input is checked or unchecked, we need to update the selectedOptions accordingly and call the onChange callback:

// src/components/MultiSelectDropdown.jsx

// ...

const handleChange = (e) => {
  const isChecked = e.target.checked;
  const option = e.target.value;

  const selectedOptionSet = new Set(selectedOptions);

  if (isChecked) {
    selectedOptionSet.add(option);
  } else {
    selectedOptionSet.delete(option);
  }

  const newSelectedOptions = Array.from(selectedOptionSet);

  setSelectedOptions(newSelectedOptions);
  onChange(newSelectedOptions);
};

// ...

Do not forget to pass the handleChange function as onChange handler to every input that is rendered:

// src/components/MultiSelectDropdown.jsx

// ...

options.map((option, i) => {
  return (
    <li key={option}>
      <label className="flex whitespace-nowrap cursor-pointer px-2 py-1 transition-colors hover:bg-blue-100 [&:has(input:checked)]:bg-blue-200">
        <input
          type="checkbox"
          name={formFieldName}
          value={option}
          className="cursor-pointer"
          onChange={handleChange}
        />
        <span className="ml-1">{option}</span>
      </label>
    </li>
  );
})

// ...

And let’s pass a debugger function to the component instance so that we can test that it works:

{/* src/app/page.js */}

{/* ... */}

<MultiSelectDropdown
  formFieldName={"countries"}
  options={COUNTRIES}
  onChange={(selectedCountries) => {
    console.debug("selectedCountries", selectedCountries);
  }}
/>

{/* ... */}

Now the array of selected options should be printed out every time the selection changes:

Selection changes reflected in the console

Select all and Clear selection

It would be also nice to add some helper buttons for the user to be able to quickly select all the options and to quickly reset the selection.

// src/components/MultiSelectDropdown.jsx

"use client";

import { useState, useEffect } from "react";

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange
}) {
  const [isJsEnabled, setIsJsEnabled] = useState(false);
  const [selectedOptions, setSelectedOptions] = useState([]);

  useEffect(() => {
    setIsJsEnabled(true);
  }, []);

  const isSelectAllEnabled = selectedOptions.length < options.length;
  const isClearSelectionEnabled = selectedOptions.length > 0;

  // ...
}

// src/components/MultiSelectDropdown.jsx

"use client";

import { useState, useEffect, useRef } from "react";

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange
}) {
  // ...

  const optionsListRef = useRef(null);

  // ...

  return (
    <label className="relative">
      {/* ... */}

      <div className="absolute bg-white border transition-opacity opacity-0 pointer-events-none peer-checked:opacity-100 peer-checked:pointer-events-auto">
        {/* ... */}
        <ul ref={optionsListRef}>
          {options.map((option, i) => {/* ... */}
        </ul>
      </div>
    </label>
  );
}

// src/components/MultiSelectDropdown.jsx

// ...

export default function MultiSelectDropdown({
  formFieldName,
  options,
  onChange
}) {
  // ...

    const handleSelectAllClick = (e) => {
      e.preventDefault();

      const optionsInputs = optionsListRef.current.querySelectorAll("input");
      optionsInputs.forEach((input) => {
        input.checked = true;
      });

      setSelectedOptions([...options]);
      onChange([...options]);
    };

    const handleClearSelectionClick = (e) => {
      e.preventDefault();

      const optionsInputs = optionsListRef.current.querySelectorAll("input");
      optionsInputs.forEach((input) => {
        input.checked = false;
      });

      setSelectedOptions([]);
      onChange([]);
    };

  // ...
}

Do not forget to bind the functions to the according buttons:

{/* src/components/MultiSelectDropdown.jsx */}

{/* ... */}

<ul>
  <li>
    <button
      onClick={handleSelectAllClick}
      disabled={!isSelectAllEnabled}
      className="w-full text-left px-2 py-1 text-blue-600 disabled:opacity-50"
    >
      {"Select All"}
    </button>
  </li>
  <li>
    <button
      onClick={handleClearSelectionClick}
      disabled={!isClearSelectionEnabled}
      className="w-full text-left px-2 py-1 text-blue-600 disabled:opacity-50"
    >
      {"Clear selection"}
    </button>
  </li>
</ul>

{/* ... */}

Now it should be much easier to select all the elements at once or to reset the selection:

Helper buttons when JavaScript is enabled

And if you disable JavaScript, the buttons won’t show up, but the component will still function:

Helper buttons are hidden when JavaScript is disabled

Wrapping up

That was a lot. I won’t be adding the polishing steps here, you can check them out here and here.

Feedback

Full source code is available here:

prutya / tutorial-multi-select-dropdown

A guide on implementing an uncontrolled Multi-Select Dropdown component with React and Tailwind CSS. The component is going to remain functional even when JavaScript is disabled on the client.

05_react-multi-select-dropdown

View on GitHub

If you have any feedback, please feel free to submit an Issue.

My original blog post

How I optimized SVG icons on my website

Anton Prudkohliad — Wed, 08 May 2024 16:01:30 +0000

So I was looking at my website the other day, at the bookmarks page in particular. What I realized was that every bookmark had an embedded SVG icon next to it:

Places where embedded SVG elements are located

That little arrow telling you that the link will open in a new tab actually looks like this:

<svg
  id="svg-icon-external-link"
  viewBox="0 0 24 24"
  fill="currentColor"
>
  <path d="M8 7C8 6.44772 8.44772 6 9 6L17 6C17.5523 6 18 6.44772 18 7V15C18 15.5523 17.5523 16 17 16C16.4477 16 16 15.5523 16 15V9.41421L7.70711 17.7071C7.31658 18.0976 6.68342 18.0976 6.29289 17.7071C5.90237 17.3166 5.90237 16.6834 6.29289 16.2929L14.5858 8L9 8C8.44772 8 8 7.55228 8 7Z"></path>
</svg>

And since there are 20 bookmarks per page, this thing is duplicated all over the page. So inefficient! This made me wonder if there was a way to have only one definition of the icon on the page and just reference it from all those 20 places. And as it turned out, there indeed was a way!

Enter <use> and <symbol> elements

As MDN says, the <use> element takes nodes from within the SVG document and duplicates them somewhere else. The effect is the same as if the nodes were deeply cloned into a non-exposed DOM and then pasted where the <use> element is.

It can be used in combination with symbol and defs elements that define the “template” to reuse an SVG. In other words - the <symbol> is an “object” and the <use> works as a “pointer” to that object.

SVG <symbol> referenced by <use> pointers

The implementation

So, I created an <svg> at the beginning of the <body> with all the icons that I have inside as <symbol> elements within a <defs>:

<!-- At the beginning of the <body> element -->
<svg width="0" height="0">
  <defs>
        <!-- The icon template definition -->
    <symbol
      id="svg-icon-external-link"
      viewBox="0 0 24 24"
      fill="currentColor"
    >
      <path d="M8 7C8 6.44772 8.44772 6 9 6L17 6C17.5523 6 18 6.44772 18 7V15C18 15.5523 17.5523 16 17 16C16.4477 16 16 15.5523 16 15V9.41421L7.70711 17.7071C7.31658 18.0976 6.68342 18.0976 6.29289 17.7071C5.90237 17.3166 5.90237 16.6834 6.29289 16.2929L14.5858 8L9 8C8.44772 8 8 7.55228 8 7Z"></path>
    </symbol>

        <!-- ... Other icons ... -->
  </defs>
</svg>

Every icon must have a unique id because we are going to pass it to our <use> elements as a href attribute to point to the definitions. Also notice the width="0" height="0" attributes - if they are not specified, the icon definitions will take actual space in the document, which might affect the layout of your page.

I also replaced every embedded <path> with a <use> pointing to the id of the according <symbol> (with a # at the beginning of the id):

<svg height="18" width="18">
  <!-- Instead of embedding a <path> element -->
  <use href="#svg-icon-external-link" />
</svg>

The result

The page still looks the same:

Icons after the optimization

But, we managed to shave a couple of kilobytes off the page though (13.5 kB before vs 11.4kB after):

Chrome web inspector showing the difference between page sizes

Considerations

Of course, such optimization will most likely be negligible in this case, but it is a great technique to have in your arsenal for situations when you have an SVG-heavy page (like Twitter, for example, with all their “like” and “repost” buttons).

Another great thing about this technique is that it promotes the DRY principle - you have only one thing and reuse it if necessary. If the icon needs to be changed, you only have to edit a single place in the codebase.

My original blog post

How to set up a new project using Yarn

Anton Prudkohliad — Wed, 08 May 2024 15:47:09 +0000

Setting up nodenv

brew install nodenv

After that, add the following line to the bottom of your .zshrc or .bashrc file (for me it is located in the home directory, a.k.a. ~):

# ~/.zshrc

# ...

eval "$(nodenv init -)"

From now on, every time you run node, nodenv will automatically pick the Node.js version specified in a .node-version file.

Setting up Node

Now, let’s create our project directory and add the latest Long Term Support version of Node.js (at the moment of writing it’s 18.16.0, check the Node.js website if you’re not sure) to the .node-version file:

# Create the project directory
mkdir project

# Change into it
cd project

# Tell nodenv to use Node 18.16.0 in your project's directory
echo "18.16.0" > .node-version

To smoke-test the installation, run

node --version

If there’s no such Node installation on your machine (which was the case for me), you’ll see an output similar to this:

nodenv: version `18.16.0' is not installed (set by /Users/anton/project/.node-version)

To fix that, use nodenv to install the Node version specified in the .node-version file:

nodenv install $(cat .node-version)

Nodenv will download and install Node:

Downloading node-v18.16.0-darwin-x64.tar.gz...
-> https://nodejs.org/dist/v18.16.0/node-v18.16.0-darwin-x64.tar.gz
Installing node-v18.16.0-darwin-x64...
Installed node-v18.16.0-darwin-x64 to /Users/anton/.nodenv/versions/18.16.0

Now our little smoke-test should return the correct version:

node --version
# => v18.16.0

Setting up Yarn

Yarn is a package manager — a tool that allows you to use code from other developers. As Yarn installation documentation mentions, the preferred way to install Yarn is to use Corepack - a built-in tool for “managing versions of your package managers”. Let’s enable Corepack and install the stable version of Yarn:

# Enable Corepack
corepack enable

# Install Yarn
corepack prepare yarn@stable --activate

Run a smoke-test to see if the installation was successful. The following command should return a version, for me it was 3.6.0:

yarn --version
# => 3.6.0

Setting up the project

Now that we have our package manager in place, let’s use it to initialize the project:

yarn init

The command above will create several configuration files and initialize a git repository in our project folder, here’s what some of them are for:

.editorconfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. Find more information on the EditorConfig website if you’re curious.
.gitattributes helps git manage your project files better. See more information on the git website.
.gitignore specifies which files are not supposed to be tracked by git. See more information here.
.yarnrc.yml contains Yarn configuration. See more in Yarnrc files documentation.
package.json contains information about the package, such as name, packageManager, and so on.
README.md is a Markdown file where you can write some documentation.
yarn.lock helps Yarn get consistent installs of dependencies (packages) across different machines. Find more in yarn.lock documentation.

We are not going to use Plug’n’Play or Zero-Installs, because those two have their pros and cons and are considered advanced features, so let’s disable them. To do that, we are going to change the .gitignore file so that the !.yarn/cache line is commented out instead of pnp.*. We will also add a node_modules line:

# .gitignore

.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

# Swap the comments on the following lines if you don't wish to use zero-installs
# Documentation here: https://yarnpkg.com/features/zero-installs
# !.yarn/cache
.pnp.*

node_modules

Next, we will update the .yarnrc.yml file. Set the nodeLinker property to node-modules so that our packages are installed in the old-fashioned manner:

# .yarnrc.yml

yarnPath: .yarn/releases/yarn-3.6.0.cjs
nodeLinker: node-modules

Finalize the setup by running yarn install or just yarn. This will create the node_modules directory.

Smoke test

Let’s make sure that we can packages and run code. We will install lodash, call a function from it, and print the output.

Install lodash:

yarn add lodash

Create an index.js file with the following content:

// index.js

const now = require("lodash/now");

console.log(now());

Run the index.js, it will print the current timestamp:

yarn node index.js
# => 1686935711710

That’s it! Now you can use this setup as a solid foundation for your future app.

Feedback

You can find the source code here:

prutya / tutorial-project-setup-yarn

How to set up a new project using Yarn

03_project-setup-yarn

View on GitHub

If you have any feedback, please feel free to submit an Issue.

My original blog post

How to resize images for Open Graph and Twitter using sharp

Anton Prudkohliad — Wed, 08 May 2024 10:51:09 +0000

When sharing content on social media platforms, it's essential to have visually appealing images that are properly sized. Let’s explore how we could automatically resize images for Open Graph and Twitter card previews. We’ll be using sharp - a powerful and fast tool that powers the Image component from Next.js.

The final result is going to look like this:

Example result (Twitter card)

Initial setup

If you need help with setting up the project, I recommend that you follow this guide from Yarn documentation.

Create two directories for input and output files:

mkdir ./input
mkdir ./output

Also, let’s put two files: example-1.jpeg (3:4) and example-2.jpeg (wide) into the input directory:

Test input image, example-1, 3:4 Test input image, example-2, wide

Install sharp and tsx (we will need it to run the script):

yarn add sharp tsx

The resizing script

Now, let’s create our script:

touch ./resize.js

First, we want to get the list of images that the script will be resizing and prepare the names for output files:

// resize.js

import fs from "fs";
import path from "path";

async function main() {
  const srcDir = "./input";
  const destDir = "./output";

  const inputFileNames = await fs.promises.readdir(srcDir);

  console.debug("inputFileNames", inputFileNames);
  // => 
  // inputFileNames [ 'example-1.jpeg', 'example-2.jpeg' ]

  for (let i = 0; i < inputFileNames.length; i++) {
    const fileFullName = inputFileNames[i];
    const extension = path.extname(fileFullName);
    const fileName = fileFullName.replace(extension, "");

    const src = path.join(srcDir, fileFullName);
    const destOpenGraph = path.join(destDir, `${fileName}.open-graph.webp`);
    const destTwitter = path.join(destDir, `${fileName}.twitter.webp`);

    console.debug({ src, destOpenGraph, destTwitter });
  }
  // =>
  // {
  //   src: 'input/example-1.jpeg',
  //   destOpenGraph: 'output/example-1.open-graph.webp',
  //   destTwitter: 'output/example-1.twitter.webp'
  // }
  // {
  //   src: 'input/example-2.jpeg',
  //   destOpenGraph: 'output/example-2.open-graph.webp',
  //   destTwitter: 'output/example-2.twitter.webp'
  // }
}

main().catch((err) => console.error(err));

Next, let’s write our image transformation function and call it two times: for Open Graph dimensions (1200×628) and for Twitter card dimensions (800×418). It will take the input path src, the output path dest, the width and height as arguments. Then it will read the input file, resize it and store the result as a webp file:

// resize.js

import fs from "fs";
import path from "path";
import sharp from "sharp";

async function main() {
  const srcDir = "./input";
  const destDir = "./output";

  const inputFileNames = await fs.promises.readdir(srcDir);

  for (let i = 0; i < inputFileNames.length; i++) {
    const fileFullName = inputFileNames[i];
    const extension = path.extname(fileFullName);
    const fileName = fileFullName.replace(extension, "");

    const src = path.join(srcDir, fileFullName);
    const destOpenGraph = path.join(destDir, `${fileName}.open-graph.webp`);
    const destTwitter = path.join(destDir, `${fileName}.twitter.webp`);

    console.debug({ src, destOpenGraph, destTwitter });

    // Open Graph
    await transform(src, destOpenGraph, 1200, 628);

    // Twitter
    await transform(src, destTwitter, 800, 418);
  }
}

async function transform(src, dest, width, height) {
  await sharp(src)
    .resize({ width, height, fit: "cover" })
    .webp({ quality: 80 })
    .toFile(dest);
}

main().catch((err) => console.error(err));

Now we can run the script using tsx:

yarn tsx resize.js

This will produce the following results:

Resized image, example-1 Resized image, example-2

However, the images are zoomed in and cropped. This might or might not be what you want. With current examples, this looks okay, but if the picture was a portrait, the person could appear partially out of the frame.

Zoomed-in and blurred background

If you’re not comfortable with that, let’s make sure that the aspect ratio is preserved and the rest of the image is taken by blurred and zoomed-in version of the same image. The function will be doing two resizes: one for the background (with blur), and another for the foreground, and combining these two layers to create the final image. Adjust the transform function as follows:

// resize.js

import fs from "fs";
import path from "path";
import sharp from "sharp";

async function main() { /* ... */ }

async function transform(src, dest, width, height) {
  const metadata = await sharp(src).metadata();

  // Calculate the source and the target aspect ratio
  const srcAspectRatio = metadata.width / metadata.height;
  const destAspectRatio = width / height;

  // Resize the image so that it covers the target dimensions, apply blur and
  // store the result in memory
  const backgroundBuffer = await sharp(src)
    .resize({ width, height, fit: "cover" })
    .blur(10)
    .toBuffer();

  // Resize the image so that it's contained within the target dimensions and
  // store the result in memory
  const foregroundBuffer = await sharp(src)
    .resize(srcAspectRatio > destAspectRatio ? { width } : { height })
    .toBuffer();

  // Combine the background and the foreground and store the result in a file
  await sharp(backgroundBuffer)
    .composite([{ input: foregroundBuffer, gravity: "center" }])
    .webp({ quality: 80 })
    .toFile(dest);
}

main().catch((err) => console.error(err));

The resulting images will look like this:

The final result, example-1 The final result, example-2

Now you can use this technique to preprocess images during the build pipeline of your application.

Feedback

You can find the source code here:

prutya / tutorial-resize-images

How to resize images for Open Graph and Twitter using sharp

02_sharp-resize

View on GitHub

If you have any feedback, please feel free to submit an Issue.

My original blog post