DEV Community: Nemanja Mitic

Runtime environment variables in Next.js - build reusable Docker images

Nemanja Mitic — Sun, 14 Dec 2025 08:17:27 +0000

Classification of environment variables by dimension

At first glance, you might think of environment variables as just a few values needed when the app starts, but as you dig deeper, you realize it's far more complex than that. If you don’t clearly understand the nature of the value you're dealing with, you'll have a hard time running the app and managing its configuration across multiple environments.

Let's identify a few dimensions that any environment variable can have:

When: build-time, start-time, run-time
Where: server (static, SSR (request), ISR), client
Visibility: public, private
Requirement: optional, required
Scope: common for all environments (constant, config), unique
Mutability: constant, mutable
Git tracking: versioned, ignored

There are probably more, but this is enough to understand why it can be challenging to manage. We could go very wide, write a long article and elaborate each of these and their combinations, but since the goal of this article is very specific and practical - handling Next.js environment variables in Docker, we'll focus just on the top three items from the list. Still, it was worth mentioning the others for context.

Next.js environment variables

If you search the Next.js docs, you will find a guide on environment variables, such as .env* filenames that are loaded by default, their load order and priority, variable expansion, and exposing and inlining variables with the NEXT_PUBLIC_ prefix into the client. In the self-hosting guide, you will also find a paragraph about opting into dynamic rendering so that variable values are read on each server component render, not just once at build time, and how this is useful for reusable Docker images.

The problem with build-time environment variables

A common scenario after reading the docs is to be aware of NEXT_PUBLIC_ and server variables and then scatter them around the codebase. If you use Docker and GitHub Actions, you will typically end up with something like this:

11c8a512.../frontend/Dockerfile

# frontend/Dockerfile

# Next.js app installer stage
FROM base AS installer
RUN apk update
RUN apk add --no-cache libc6-compat

# Enable pnpm
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
RUN corepack enable
RUN corepack prepare pnpm@10.12.4 --activate

WORKDIR /app

# Copy monorepo package.json and lock files
COPY --from=builder /app/out/json/ .
# Install the dependencies
RUN pnpm install --frozen-lockfile

# Copy pruned source
COPY --from=builder /app/out/full/ .

# THIS: set build time env vars
ARG ARG_NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$ARG_NEXT_PUBLIC_SITE_URL
RUN echo "NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL"

ARG ARG_NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$ARG_NEXT_PUBLIC_API_URL
RUN echo "NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL"

# Build the project
RUN pnpm turbo build

# ...

11c8a512.../.github/workflows/build-push-frontend.yml

# .github/workflows/build-push-docker-image.yml

name: Build and push Docker frontend

on:
  push:
    branches:
      - 'main'
  workflow_dispatch:

env:
  IMAGE_NAME: ${{ github.event.repository.name }}-frontend
  # THIS: set build time env vars
  NEXT_PUBLIC_SITE_URL: 'https://full-stack-fastapi-template-nextjs.arm1.nemanjamitic.com'
  NEXT_PUBLIC_API_URL: 'https://api.full-stack-fastapi-template-nextjs.arm1.nemanjamitic.com'

jobs:
  build:
    name: Build and push docker image
    runs-on: ubuntu-latest
    steps:
      # ...

      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          context: ./frontend
          file: ./frontend/Dockerfile
          platforms: linux/amd64,linux/arm64
          progress: plain
          # THIS: set build time args
          build-args: |
            "ARG_NEXT_PUBLIC_SITE_URL=${{ env.NEXT_PUBLIC_SITE_URL }}"
            "ARG_NEXT_PUBLIC_API_URL=${{ env.NEXT_PUBLIC_API_URL }}"
          push: true
          tags: ${{ secrets.DOCKER_USERNAME }}/${{ env.IMAGE_NAME }}:latest

11c8a512.../frontend/package.json

// frontend/package.json

{
  "name": "full-stack-fastapi-template-nextjs",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "standalone": "turbo run standalone --filter web",
    // THIS: set build time args
    "docker:build:x86": "docker buildx build -f ./Dockerfile -t nemanjamitic/full-stack-fastapi-template-nextjs-frontend --build-arg ARG_NEXT_PUBLIC_SITE_URL='full-stack-fastapi-template-nextjs.local.nemanjamitic.com' --build-arg ARG_NEXT_PUBLIC_API_URL='api.full-stack-fastapi-template-nextjs.local.nemanjamitic.com' --platform linux/amd64 ."

    // ...
  }

  // ...
}

In the code above, we can see that our Next.js app requires the NEXT_PUBLIC_SITE_URL and NEXT_PUBLIC_API_URL environment variables at build time. These values will be inlined into the bundle during the build and cannot be changed later. This means the Dockerfile must pass them as the corresponding ARG_NEXT_PUBLIC_SITE_URL and ARG_NEXT_PUBLIC_API_URL build arguments when building the image.

Leaving them undefined would break the build because they are validated with Zod inside the Next.js app, and validation runs at both build time and run time. Stripping the NEXT_PUBLIC_ prefix would also break the build, even without Zod, if they are used in client code.

Consequently, we need to pass these build arguments whenever we build the Docker image, for example in GitHub Actions and in the local build script defined in package.json.

Using this method, we would get a functional Docker image, but with one major drawback: it can be used only in a single environment because the NEXT_PUBLIC_SITE_URL and NEXT_PUBLIC_API_URL values are baked into the image at build time and are immutable.

To make this crystal clear, whatever we set for the NEXT_PUBLIC_SITE_URL and NEXT_PUBLIC_API_URL environment variables at runtime will be ignored because they no longer exist in the Next.js app. After the build they are replaced with string literals in the JavaScript bundle.

If, besides production, you also have staging, preview, testing environments, or other production mirrors, you would need to maintain a separate image with its own configuration code, build process, and registry storage for each of them. This means a lot of overhead.

Many people find this impractical, which you can see from the popularity of such issues in the Next.js repository:

Better support for runtime environment variables #44628

Docker image with NEXT*PUBLIC* env variables #17641

Not possible to use different configurations in staging + production #22243

The solution: run-time environment variables

The solution is obvious: we should prevent any use of build-time (stale, immutable) variables and read everything from the target environment at runtime. This also means avoiding any NEXT_PUBLIC_* client variables.

To implement this, we must be well aware of where and when a given component runs:

Server component - runs on the server, generated at build time or at request time
Static page - runs on the server, generated once at build time
Client component - runs in the browser, generated at build time or at request time

Server component

These components (or entire pages) are dynamically rendered on each request. They have access to any server data, including both public and private environment variables. No additional action is needed. In Next.js, we identify such components by their use of request resources such as cookies, headers, and connection:

import { cookies, headers } from 'next/headers';
import { connection } from 'next/server';

export default async function Page() {
  const headersList = await headers();
  const cookiesList = await cookies();

  await connection(); // void
}

Static page

Such a page is pre-rendered once at build time in the build environment. It has access to server data, but it is converted to a static asset at build time and is immutable at runtime. We have two options:

Convert it to a dynamic page that is rendered on the server on each request.

import { connection } from 'next/server';

export default async function Page() {
  // opt into dynamic rendering
  await connection();

  // ...
}

Set placeholder values for variables at build time and perform string replacement directly on the generated static HTML using sed or envsubst and a shell script included in ENTRYPOINT ["scripts/entrypoint.sh"] in the Dockerfile.

Note that these will be start-time variables, not true run-time variables, but most of the time that is sufficient because they are unique to each environment. However, they cannot change during the app's run time once initialized.

We won't go into much detail about this method, it could be a good topic for a future article since it is quite useful for static, presentational websites. If you want to read more, here is an interesting and practical tutorial: https://phase.dev/blog/nextjs-public-runtime-variables/.

Client component

Next.js prevents exposing any variables to the client without the NEXT_PUBLIC_ prefix, but since those are inlined at build time, we simply won't use them. For exposing environment variables to client components, we have a few options:

Pass variables as props from the parent server component like any other value. This is simple and convenient.
Inside the dynamically generated root layout, render a <script /> tag that injects a window.__RUNTIME_ENV__ property into the global window object using the dangerouslySetInnerHTML attribute. We will actually use this method. Then, on the client, we can access the variables on the window object, for example window.__RUNTIME_ENV__.API_URL.

Also this is a good moment to validate runtime vars with Zod.

Here is the illustration code bellow:

// app/layout.tsx

import { connection } from 'next/server';

export const runtimeEnvSchema = z.object({
  SITE_URL: z.url().regex(/[^/]$/, 'SITE_URL should not end with a slash "/"'),
  API_URL: z.url().regex(/[^/]$/, 'API_URL should not end with a slash "/"'),
});

const RootLayout: FC<Props> = async ({ children }) => {
  await connection();

  const runtimeEnvData = {
    SITE_URL: process.env.SITE_URL,
    API_URL: process.env.API_URL,
  };

  // validate vars with Zod before injecting
  const parsedRuntimeEnv = runtimeEnvSchema.safeParse(runtimeEnvData);

  // if invalid vars abort
  if (!parsedRuntimeEnv.success) throw new Error('Invalid runtime environment variable found...');

  const runtimeEnv = parsedRuntimeEnv.data;

  return (
    <html lang="en">
      <body>
        {/* Inline JSON injection */}
        <script
          dangerouslySetInnerHTML={{
            __html: `window.__RUNTIME_ENV__ = ${JSON.stringify(runtimeEnv)};`,
          }}
        />

        {children}
      </body>
    </html>
  );
};

Same as for static pages: set placeholder values and use sed to replace them with a shell script inside the JavaScript bundle when the container starts.
Expose variables through a dynamic API endpoint and perform an HTTP fetch in client components. This is a legitimate method, but note that it will make the variables asynchronous.

We can see from this that the first two methods are the simplest and most convenient, so we will use them.

Note: Whenever an environment variable is available on the client, it is public by default. Make sure not to expose any secrets to the client.

`alizeait/next-public-env` package

We could do this manually as shown in the snippet above, but there is already the alizeait/next-public-env package that handles all of this and also provides some more advanced handling.

Check these 2 files for example:

Usage is obvious and straightforward: just define a Zod schema, mount <PublicEnv /> in the root layout, and use getPublicEnv() to access the variables wherever you need them.

You can see bellow how I did it:

# install package

pnpm add next-public-env

frontend/apps/web/src/config/process-env.ts

// frontend/apps/web/src/config/process-env.ts

/** Exports RUNTIME env. Must NOT call getPublicEnv() in global scope. */
export const { getPublicEnv, PublicEnv } = createPublicEnv(
  {
    NODE_ENV: process.env.NODE_ENV,
    SITE_URL: process.env.SITE_URL,
    API_URL: process.env.API_URL,
  },
  { schema: (z) => getProcessEnvSchemaProps(z) }
);

frontend/apps/web/src/schemas/config.ts

// frontend/apps/web/src/schemas/config.ts

import { z } from 'zod';

export const nodeEnvValues = ['development', 'test', 'production'] as const;

type ZodType = typeof z;

/** For runtime env. */
export const getProcessEnvSchemaProps = (z: ZodType) => ({
  NODE_ENV: z.enum(nodeEnvValues),
  SITE_URL: z.url().regex(/[^/]$/, 'SITE_URL should not end with a slash "/"'),
  API_URL: z.url().regex(/[^/]$/, 'API_URL should not end with a slash "/"'),
});

/** For schema type. */
export const processEnvSchema = z.object(getProcessEnvSchemaProps(z));

frontend/apps/web/src/app/layout.tsx

// frontend/apps/web/src/app/layout.tsx

import { PublicEnv } from '@/config/process-env';

interface Props {
  children: ReactNode;
}

const RootLayout: FC<Props> = ({ children }) => (
  <html lang="en" suppressHydrationWarning>
    <body className={fontInter.className}>
      <PublicEnv />
      <ThemeProvider attribute="class" defaultTheme="light" enableSystem disableTransitionOnChange>
        {/* Slot with server components */}
        {children}
        <Toaster />
      </ThemeProvider>
    </body>
  </html>
);

export default RootLayout;

An example usage, for instance in instrumentation.ts, to log the runtime values of all environment variables for debugging purposes:

frontend/apps/web/src/instrumentation.ts

// frontend/apps/web/src/instrumentation.ts

/** Runs only once on server start. */

/** Log loaded env vars. */
export const register = async () => {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { prettyPrintObject } = await import('@/utils/log');
    const { getPublicEnv } = await import('@/config/process-env');

    prettyPrintObject(getPublicEnv(), 'Runtime process.env');
  }
};

Usage for `baseUrl` for OpenAPI client

This is another typical and very important spot for using the API_URL environment variable. What makes it tricky is that it is included and runs on both the server and in the browser, but it is defined in a single place.

However, alizeait/next-public-env resolves this complexity very well on its own, and you can simply use getPublicEnv() to get the API_URL value while letting the package handle the rest.

frontend/apps/web/src/lib/hey-api.ts

// frontend/apps/web/src/lib/hey-api.ts

import { getPublicEnv } from '@/config/process-env';

/** Runtime config. Runs and imported both on server and in browser. */
export const createClientConfig: CreateClientConfig = (config) => {
  const { API_URL } = getPublicEnv();

  return {
    ...config,
    baseUrl: API_URL,
    credentials: 'include',
    ...(isServer() ? { fetch: serverFetch } : {}),
  };
};

Legitimate build-time environment variables

Variables that are the same for every environment can be left as NEXT_PUBLIC_ and inlined into the bundle. They should also be versioned in Git (their .env.* files). Since this is the case, the best approach is to store them as TypeScript constants directly in the source, because that is what they truly are - shared constants.

Build and deploy reusable Docker image

Build once - deploy everywhere. Use a single image and .env file with no redundancy.

Building

Now that we have eliminated all build-time variables by converting them to run-time environment variables, we can simply remove all build arguments and environment variables from the Dockerfile, Github Actions build workflow, package.json build scripts, etc.

Note: During the build phase of a Next.js app, the global scope is also executed. Therefore, if you read any environment variables, such as process.env.MY_VAR_XXX, your code must be able to handle a default undefined value without throwing exceptions, as this would break the build.

Tip: To access environment variables, always use getPublicEnv() inside components and functions. Never call getPublicEnv() or read process.env in the global scope, this way, you won't need to handle undefined environment variables explicitly for the build to pass.

Simply remove all build arguments and build-time environment variables from the Dockerfile:

# frontend/Dockerfile

# Not needed anymore, remove all build args
ARG ARG_NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$ARG_NEXT_PUBLIC_SITE_URL
RUN echo "NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL"

ARG ARG_NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$ARG_NEXT_PUBLIC_API_URL
RUN echo "NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL"

This is the cleaned up Dockerfile that I am using to build Next.js app inside the monorepo: frontend/Dockerfile.

Also, don't forget to clean up unused build arguments from the Github Actions workflow and package.json scripts for building the Docker image. You can see mine here: .github/workflows/build-push-frontend.yml, frontend/package.json.

// frontend/package.json

"scripts": {
  "docker:build:x86": "docker buildx build -f ./Dockerfile -t nemanjamitic/full-stack-fastapi-template-nextjs-frontend --platform linux/amd64 ."
},

Deployment

Once built, you can use that image to deploy to any environment. Naturally, you need to define and pass all runtime environment variables into the Docker container. In your docker-compose.yml, use the env_file: or environment: keys.

# apps/full-stack-fastapi-template-nextjs/docker-compose.yml

services:
  frontend:
    image: nemanjamitic/full-stack-fastapi-template-nextjs-frontend:latest
    container_name: full-stack-fastapi-template-nextjs-frontend
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - PORT=3000

    # ...

# apps/full-stack-fastapi-template-nextjs/.env

SITE_URL=https://full-stack-fastapi-template-nextjs.arm1.nemanjamitic.com
API_URL=https://api-full-stack-fastapi-template-nextjs.arm1.nemanjamitic.com
NODE_ENV=production

# ...

You can see docker-compose.yml and .env I am using here: apps/full-stack-fastapi-template-nextjs/docker-compose.yml, apps/full-stack-fastapi-template-nextjs/.env.example

Alternative approaches

In the Static page section, I already mentioned a few notes about runtime variables and static websites. Indeed, you have two options for runtime variables:

Convert the website from static to dynamically rendered SSR (rendered at request time). Note that this is a significant change: from this point, your website will require a Node.js runtime, which will greatly impact your deployment options, as you can no longer use static hosting.

This is overkill just for the purpose of having runtime environment variables. Use it only if your website has additional reasons to use SSR.

Perform string replacement directly on bundle assets using sed, envsubst, etc. This is the right approach. There are other options, such as the Nginx subs_filter config option, but be careful with it, as it runs on each request and can waste CPU.

Another option to consider is using an ./env.js file instead of the usual .env. You can then host it with Nginx and load it into the app using <script src="./env.js" />. After that, you can reference the variables with window.__RUNTIME_ENV__.MY_VAR.

Note that this won't work well for usage in pure HTML pages. For example, Astro omits any client-side JavaScript by default, so you would need to use an additional inline <script /> tag to update the HTML, e.g., getElementById("my-id")?.textContent = window.__RUNTIME_ENV__.MY_VAR, which is less optimal than the string replacement method.

Here is a quick, approximate code for illustration:

// env.js

// define variables

window.__RUNTIME_ENV__ = {
  SITE_URL: 'https://my-static-website.com',
  PLAUSIBLE_DOMAIN: 'my-static-website.com',
  PLAUSIBLE_SCRIPT_URL: 'https://plausible.my-server.com/js/script.js',
};

# docker-compose.yml

# mount and host env.js file

my-static-website:
  image: nginx:1.29.1-alpine3.22-slim
  container_name: my-static-website
  restart: unless-stopped
  volumes:
    - ./website:/usr/share/nginx/html
    - ./env.js:/usr/share/nginx/html/env.js # this
    - ./nginx/nginx.conf:/etc/nginx/nginx.conf

  # ...

<!-- src/components/BaseHead.astro -->

<!-- Load env.js file -->

<head>
  <meta charset="UTF-8" />
  <title>My static website</title>

  <script src="./env.js"></script>

  <!-- ... -->
</head>

<!-- src/components/MyComponent.astro -->

<!-- example usage -->

<!-- example 1: assign var to text content -->
<span id="my-element"></span>

<script>
  const mySpan = document.getElementById('my-element');
  mySpan.textContent = window.__RUNTIME_ENV__.MY_VAR;
</script>

<!-- example 2: assign var to script attribute -->
<script>
  const script = document.createElement('script');
  script.defer = true;
  script.type = 'text/partytown';

  // dynamically set attributes from runtime env
  script.dataset.domain = window.__RUNTIME_ENV__.PLAUSIBLE_DOMAIN;
  script.src = window.__RUNTIME_ENV__.PLAUSIBLE_SCRIPT_URL;

  document.head.appendChild(script);
</script>

So, to conclude, the best approach is to use a shell script with sed or envsubst and add it to the Nginx Dockerfile ENTRYPOINT or the docker-compose.yml command:. Here is the link to the already mentioned practical tutorial again: https://phase.dev/blog/nextjs-public-runtime-variables/.

Completed code

Next.js app repository: https://github.com/nemanjam/full-stack-fastapi-template-nextjs/tree/main/frontend/apps/web
Deployment repository: https://github.com/nemanjam/traefik-proxy/tree/main/apps/full-stack-fastapi-template-nextjs

The relevant files:

# 1. Next.js app repo

# https://github.com/nemanjam/full-stack-fastapi-template-nextjs/tree/e990a3e29b7af60831851ff6f909c34df6a7f800

git checkout e990a3e29b7af60831851ff6f909c34df6a7f800

# run-time vars configuration
frontend/apps/web/src/config/process-env.ts
frontend/apps/web/src/schemas/config.ts
frontend/apps/web/src/app/layout.tsx

# usages
frontend/apps/web/src/instrumentation.ts
frontend/apps/web/src/lib/hey-api.ts

# 2. Deployment repo

# https://github.com/nemanjam/traefik-prox/tree/f3c087184e851db20e65409a6dd145767dd9bc2b

git checkout f3c087184e851db20e65409a6dd145767dd9bc2b

apps/full-stack-fastapi-template-nextjs/docker-compose.yml
apps/full-stack-fastapi-template-nextjs/.env.example

Conclusion

If you go by inertia and mix and scatter run-time and build-time variables around the source code, build, and deployment configuration, you will end up with development and production environments that are difficult to manage, hard to debug and replicate bugs, have an unreliable deployment process, constantly require troubleshooting for missing or invalid environment variables, and result in redundant Docker images, among other issues.

So, take a proactive approach: understand properly and identify the variables you are dealing with. One way to do this is to leverage the power and convenience of run-time environment variables.

What approach do you use to manage environment variables in Next.js apps? Feel free to share your experiences and opinions in the comments.

References

How to use environment variables in Next.js, Next.js docs guide https://nextjs.org/docs/app/guides/environment-variables#runtime-environment-variables
How to self-host your Next.js application, Next.js docs guide https://nextjs.org/docs/app/guides/self-hosting#environment-variables
Better support for runtime environment variables #44628, Github discussion https://github.com/vercel/next.js/discussions/44628
Docker image with NEXT*PUBLIC* env variables #17641, Github discussion https://github.com/vercel/next.js/discussions/17641
Not possible to use different configurations in staging + production #22243, Github discussion https://github.com/vercel/next.js/discussions/22243
Runtime variables for static website, tutorial https://phase.dev/blog/nextjs-public-runtime-variables/
Runtime Environment Variables in Next.js, concise overview https://dt.in.th/NextRuntimeEnv

Comparing BFS, DFS, Dijkstra, and A* algorithms on a practical maze solver example

Nemanja Mitic — Tue, 05 Aug 2025 20:08:44 +0000

Introduction

Pathfinding is a fundamental topic in computer science, with applications in fields like navigation, AI/ML, network routing, and many others. In this article, we compare four core pathfinding algorithms: breadth-first search (BFS), depth-first search (DFS), Dijkstra’s algorithm, and A* (A star) through a practical maze-solving example. We don’t just explain them in theory, we built a demo app where you can tweak maze inputs or edit the algorithm code and instantly see how it affects the output and efficiency.

One of the key takeaways is how a tiny change, just a single line in the code can drastically alter an algorithm’s behavior. This highlights how critical implementation details are, even when the overall structure looks the same.

Problem overview

Paths in a maze form a tree structure or a graph if the maze contains cycles. That's why tree and graph traversal algorithms can be used for finding paths and the shortest path in a maze.

All 4 algorithms differ in just a few lines of code, but their behavior differs dramatically.

App architecture

We create a pragmatic, simplified OOP model of the maze and its behavior as a tradeoff, favoring clarity and concise instantiation of maze objects in tests.

Maze representation

A maze is represented as a binary matrix where 0 stands for a free space, 1 for a boundary, and * for a path. It also has start and end points. In the sense of a weighted graph 0 cell has zero weight and cell 1 has infinite weight.

// src/maze.ts

export class Maze implements IMaze {
  private board: number[][];
  private start: Coordinate;
  private end: Coordinate;

  // ...
}

export interface Coordinate {
  readonly x: number;
  readonly y: number;
}

// example maze
const testMaze: number[][] = [
  [0, 1, 0, 0, 0],
  [0, 1, 0, 1, 0],
  [0, 0, 0, 1, 0],
  [0, 1, 1, 1, 0],
  [0, 0, 0, 0, 0],
];

const start: Coordinate = { x: 0, y: 0 };
const end: Coordinate = { x: 4, y: 4 };

Class structure

We use polymorphism and a simplified Factory pattern. MazeSolver is an abstract class that declares the findPath() method, which is implemented in each derived concrete solver class.

// src/solvers/maze-solver.ts

/**
 * Abstract base class for maze solving algorithms.
 * Implements common functionality for maze solvers.
 */

export abstract class MazeSolver implements IMazeSolver {
  protected maze: IMaze;

  protected abstract findPath(): Coordinate[] | null;

  // ...
}

We use encapsulation and coding towards interface, separating interfaces from implementations by exposing only the public class methods through the interfaces.

Maze interface:

// src/types/maze.ts

export interface IMaze {
  getBoard(): number[][];

  getStart: () => Coordinate;

  formatPath: (path: ReadonlyArray<Coordinate>) => string;

  // ...
}

Maze implementation:

// src/maze.ts

export class Maze implements IMaze {
  public getBoard(): number[][] { ... }

  public getStart(): Coordinate { ... }

  public formatPath(path: ReadonlyArray<Coordinate>): string { ... }

  // ...
}

Maze usage:

// src/main.ts

const _maze2: IMaze = Maze.create(testMaze, start, end);

// ...

Class diagram:

Running the app

We install dependencies, run the app, and run the tests as usual, like any other TypeScript app.

# install dependencies
yarn install

# enable or disable logging in src/config.ts

# run the app in dev mode
yarn dev

# logging is disabled for tests by default

# run tests
yarn test

# run tests in verbose mode
yarn test-verbose

# generate coverage report
yarn coverage

We can see that different algorithms require a different number of steps for the same input maze. Example output for a given maze input:

We can run tests that ensure for each algorithm:

finds existing path
doesn't find a false non existent path
finds the shortest path.

And calculate the code coverage:

Algorithms analysis and discussion

Now for the most important and interesting part: let's analyze the algorithm's code and explain how it affects their behavior and efficiency.

Unweighted graphs

BFS and DFS are basic traversal algorithms that ignore the weights of the edges, so they are applicable only to unweighted graphs.

The actual code for BFS and DFS differs by only a single line, but they exhibit completely opposite behavior. BFS uses a queue (FIFO), while DFS uses a stack (LIFO), and this has a fundamental impact on how the next node candidate for the path is selected.

// BFS
const { coord, path } = queue.shift()!;

// DFS
const { coord, path } = stack.pop()!;

This is the array of coordinates that represents possible directions for movement. This array is iterated over in the algorithm's inner loop.

// src/utils/constants.ts

export const directions: Direction[] = [
  { x: 0, y: 1 }, // up
  { x: 1, y: 0 }, // right
  { x: 0, y: -1 }, // down
  { x: -1, y: 0 }, // left
];

Here is the complete BFS implementation (since all 4 algorithms share most of the same base) so we can have a better idea of what we are working with:

// src/solvers/maze-solver-bfs.ts

export class MazeSolverBFS extends MazeSolver {
  /**
   * Implements the Breadth-First Search (BFS) algorithm to find a path from the start to the end of the maze.
   */
  protected findPath(): Coordinate[] | null {
    const start = this.maze.getStart();

    // Initialize the BFS queue with the start position.
    const queue: BFSQueueElement[] = [{ coord: start, path: [start] }];

    // Keep track of visited coordinates (as strings).
    const visited = new Set<string>();
    visited.add(`${start.x},${start.y}`);

    while (queue.length > 0) {
      // Count iterations.
      this.incrementStep();

      // The most important line.
      // FIFO - Takes the oldest element in the queue.
      const { coord, path } = queue.shift()!;

      // Check if end and exit.
      if (this.maze.isEnd(coord)) {
        return path;
      }

      // Print the current state of the maze.
      this.printBoard(coord, visited, path);

      // Always loops 4 times.
      for (const direction of directions) {
        // Calculate the next coordinate by applying the direction.
        const nextCoord: Coordinate = {
          x: coord.x + direction.x,
          y: coord.y + direction.y,
        };
        // Create a key for nextCoord (to check for uniqueness in the visited set).
        const coordKey = `${nextCoord.x},${nextCoord.y}`;

        // If nextCoord is not visited, is within bounds, and is walkable, add it to the potential path.
        if (
          !visited.has(coordKey) &&
          this.maze.isWithinBounds(nextCoord) &&
          this.maze.isWalkable(nextCoord)
        ) {
          visited.add(coordKey);
          queue.push({ coord: nextCoord, path: [...path, nextCoord] });
        }
      }
    }

    // Return null if no path to the end is found.
    return null;
  }
}

BFS

Since BFS uses a queue, it respects this structure and attempts to change direction in every iteration of the outer loop. Without obstacles and boundaries, this causes the algorithm to thoroughly inspect nodes closer to the starting node before moving further away. That's why BFS can be inefficient for large trees and graphs where the end node is very distant from the starting node.

DFS

In contrast, DFS also respects the initial order in the directions array but prioritizes the earlier elements. So, in the example above, it will always attempt to apply the up direction first before exploring other directions. Without obstacles and boundaries, this causes the algorithm to inspect distant nodes in a straight line. DFS can be efficient for finding a distant end node but can also be very inefficient for finding a nearby node if it happens to be in a different direction.

Weighted graphs

Not all graphs have edges with uniform weights. In such cases, we must use algorithms that are aware of weights (the cost between two nodes), such as Dijkstra and A*.

Dijkstra

Dijkstra's algorithm is aware of the cost between two nodes (edge weight) and takes it into account when selecting the next node. It uses a priority queue to keep track of the cost history.

// src/solvers/maze-solver-dijkstra.ts

// Take the first element from the priority queue.
// Choose the node that ads minimal cost.
queue.sort((a, b) => a.cost - b.cost);
const { coord, path, cost } = queue.shift()!;

// ...

// Test how much cost every new node ads to the path before adding it to the queue.
const nextCost = cost + this.maze.getCost(nextCoord);
// ...
if( ... && !costMap.has(coordKey) || nextCost < costMap.get(coordKey)!)

Dijkstra keeps a history of the cost of the current path and when selecting the next node chooses the node that adds the minimal cost. If there are cycles it may access the same node from multiple paths and will choose the one with the minimal weight (shortest path). In graphs with constant edge weights it reduces to BFS. This can be observed in the screenshot above, where both BFS and Dijkstra take an equal number of steps because the maze has uniform weights of 1 and Infinity.

A*

A* is the same as Dijkstra but besides keeping the history, it uses a heuristic function to predict the future - the direction in which the end node could be.

// src/solvers/maze-solver-a-star.ts

protected heuristic(a: Coordinate, b: Coordinate): number {
    // Manhattan distance as the heuristic.
    // Can only move horizontally or vertically, not diagonally. In "rectangles".
    return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
}

// ...

openSet.sort(
  (a, b) =>
    // The most important line. The only difference from Dijkstra.
    // Cost = history + Manhattan distance from the end node.
    // prettier-ignore
    (a.cost + this.heuristic(a.coord, end)) -
    (b.cost + this.heuristic(b.coord, end))
);

If the heuristic function is well chosen it will make A* more efficient than the before mentioned algorithms. Consequently, if the heuristic function is poorly chosen it will degrade the algorithm efficiency.

Completed code

Maze solver: https://github.com/nemanjam/maze-solver

Conclusion

In this example, we can see how algorithm analysis and design is a very sensitive and subtle discipline that leaves no room for low focus or a lack of understanding of the domain. Although BFS, DFS, Dijkstra, and A* share most of their implementation, even a subtle change in the code can lead to a dramatic change in behavior.

In the demo app, you can tweak the predefined mazes in the tests/fixtures/*.txt files and make your own observations. You can also check the resources and interactive playground listed in the References section.

Have you experimented with maze-solving and pathfinding algorithms before? Let me know in the comments.

References

Some visualized algorithms behavior https://www.youtube.com/watch?v=GC-nBgi9r0U
BFS vs DFS, basic overview and implementation https://www.geeksforgeeks.org/difference-between-bfs-and-dfs/
BFS vs Dijkstra for unweighted and weighted graphs https://www.baeldung.com/cs/graph-algorithms-bfs-dijkstra
BFS vs Dijkstra similarities https://stackoverflow.com/a/52676408/4383275
Visual playgrounds https://visualmazesolver.vercel.app/, http://qiao.github.io/PathFinding.js/visual/
Starter project, Typescript, Jest https://github.com/julianmateu/hello-ts

Load balancing multiple Rathole tunnels with Traefik HTTP and TCP routers

Nemanja Mitic — Mon, 02 Jun 2025 08:51:05 +0000

Introduction

This article is a continuation of Expose home server with Rathole tunnel and Traefik article, which explains how to permanently host websites from home by bypassing CGNAT. That setup works well for exposing a single home server (like a Raspberry Pi, server PC, or virtual machine), but it has a limitation: it requires one VPS (or at least one public network interface) per home server. This is because the Rathole server exclusively uses ports 80 and 443.

But it doesn't have to be like this. We can reuse a single Rathole server for many tunnels and home servers, we just need a tool to load balance their traffic, as long as our VPS's network interface provides enough bandwidth for our websites and services.

This article explains how to achieve that using Traefik HTTP and TCP routers.

Prerequisites

A working Rathole tunnel setup from the previous article (including a VPS and a domain name)
More than one home server (Raspberry Pi, server PC, virtual machine, or LXC container)

Architecture overview

The problem

The main problem here is that we can't bind more than one port to ports 80 and 443, respectively. Only one service can listen on a given port at the same time. So something like this doesn't exist:

# docker-compose.yml

services:
  rathole:
    image: rapiz1/rathole:v0.5.0
    container_name: rathole
    command: --server /config/rathole.server.toml
    restart: unless-stopped
    ports:
      # host:container
      - 2333:2333
      - 80:5080,5081 # non existent syntax, can't bind two ports to a single port
      - 443:5443,5444 # same
    volumes:
      - ./rathole.server.toml:/config/rathole.server.toml:ro

Neither the operating system nor Docker provides load balancing functionality out of the box, we need to handle it ourselves.

The solution

We need to introduce a tool for load balancing traffic between tunnels. We will use Traefik, since we already use it with the Rathole client.

For each home server, we need 2 tunnels: one for HTTP and another for HTTPS traffic:

The tunnel for HTTP traffic will use the Traefik HTTP router as usual.
The tunnel for HTTPS traffic is a bit more interesting and challenging. For it, we will use the Traefik TCP router running in passthrough mode, since we don't want to terminate HTTPS traffic on the VPS. Instead, we want to delegate certificate resolution to the existing Traefik instance running on the client side to preserve the current setup and architecture.

Reminder:

I already wrote about the advantage of resolving SSL certificates locally on the home server in the Architecture overview section of the previous article, but here is a quick recap:

The home server contains its entire configuration
The home server is tunnel-agnostic and reusable
No coupling between the tunnel server and client, no need to maintain state or version
Decoupled debugging
Improved security, an additional encryption layer further down the tunnel

Traefik load balancer and Rathole server

Since we passthrough encrypted HTTPS traffic, Traefik can't read the subdomain from an HTTP request as usual. Instead, we will run the Traefik router in TCP mode, using the HostSNIRegexp matcher. This will run the router on layer 4 (TCP) instead of the usual layer 7 (HTTP).

For more in-depth info on how this works, you can read here: Server Name Indication (SNI).

Now that we understand the principle, we can get to the practical implementation.

Traefik HTTP and TCP routers

Below is the complete docker-compose.yml that defines the Traefik TCP router and the Rathole server with 2 HTTP/HTTPS tunnel pairs for 2 home servers: pi (OrangePi) and local (MiniPC), in my case.

# docker-compose.yml

version: '3.8'

services:
  traefik:
    image: traefik:v2.9.8
    container_name: traefik
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
      - --entrypoints.traefik.address=:8080
      - --api.dashboard=true
      - --api.insecure=false
      - --log.level=DEBUG
      - --accesslog=true
    ports:
      - 80:80
      - 443:443
      - 8080:8080
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - proxy
    labels:
      # Enable the dashboard at http://traefik.amd2.nemanjamitic.com
      # http for simplicity, no acme.json file
      - traefik.enable=true
      - 'traefik.http.routers.traefik.rule=Host(`traefik.amd2.${SITE_HOSTNAME}`)'
      - traefik.http.routers.traefik.entrypoints=web
      - traefik.http.routers.traefik.service=api@internal
      - traefik.http.routers.traefik.middlewares=auth
      - 'traefik.http.middlewares.auth.basicauth.users=${TRAEFIK_AUTH}'

  rathole:
    image: rapiz1/rathole:v0.5.0
    container_name: rathole
    command: --server /config/rathole.server.toml
    restart: unless-stopped
    ports:
      - 2333:2333
    volumes:
      - ./rathole.server.toml:/config/rathole.server.toml:ro
    networks:
      - proxy

    labels:
      ### HTTP port 80 - HTTP routers ###

      # pi.nemanjamitic.com, www.pi.nemanjamitic.com, *.pi.nemanjamitic.com, www.*.pi.nemanjamitic.com

      # Route *.pi.nemanjamitic.com -> 5080
      - 'traefik.http.routers.rathole-pi.rule=HostRegexp(`pi.${SITE_HOSTNAME}`, `www.pi.${SITE_HOSTNAME}`, `{subdomain:[a-z0-9-]+}.pi.${SITE_HOSTNAME}`, `www.{subdomain:[a-z0-9-]+}.pi.${SITE_HOSTNAME}`)'
      - traefik.http.routers.rathole-pi.entrypoints=web
      - traefik.http.routers.rathole-pi.service=rathole-pi
      - traefik.http.services.rathole-pi.loadbalancer.server.port=5080

      # Route *.local.nemanjamitic.com -> 5081
      - 'traefik.http.routers.rathole-local.rule=HostRegexp(`local.${SITE_HOSTNAME}`, `www.local.${SITE_HOSTNAME}`, `{subdomain:[a-z0-9-]+}.local.${SITE_HOSTNAME}`, `www.{subdomain:[a-z0-9-]+}.local.${SITE_HOSTNAME}`)'
      - traefik.http.routers.rathole-local.entrypoints=web
      - traefik.http.routers.rathole-local.service=rathole-local
      - traefik.http.services.rathole-local.loadbalancer.server.port=5081

      ### HTTPS port 443 with TLS passthrough - TCP routers ###

      # Route *.pi.nemanjamitic.com -> 5443
      - 'traefik.tcp.routers.rathole-pi-secure.rule=HostSNIRegexp(`pi.${SITE_HOSTNAME}`, `www.pi.${SITE_HOSTNAME}`, `{subdomain:[a-z0-9-]+}.pi.${SITE_HOSTNAME}`, `www.{subdomain:[a-z0-9-]+}.pi.${SITE_HOSTNAME}`)'
      - traefik.tcp.routers.rathole-pi-secure.entrypoints=websecure
      - traefik.tcp.routers.rathole-pi-secure.tls.passthrough=true
      - traefik.tcp.routers.rathole-pi-secure.service=rathole-pi-secure
      - traefik.tcp.services.rathole-pi-secure.loadbalancer.server.port=5443

      # Route *.local.nemanjamitic.com -> 5444
      - 'traefik.tcp.routers.rathole-local-secure.rule=HostSNIRegexp(`local.${SITE_HOSTNAME}`, `www.local.${SITE_HOSTNAME}`, `{subdomain:[a-z0-9-]+}.local.${SITE_HOSTNAME}`, `www.{subdomain:[a-z0-9-]+}.local.${SITE_HOSTNAME}`)'
      - traefik.tcp.routers.rathole-local-secure.entrypoints=websecure
      - traefik.tcp.routers.rathole-local-secure.tls.passthrough=true
      - traefik.tcp.routers.rathole-local-secure.service=rathole-local-secure
      - traefik.tcp.services.rathole-local-secure.loadbalancer.server.port=5444

networks:
  proxy:
    external: true

Let's start with the most important part: the labels on the rathole container that define load balancing on the two tunnels.

First, we define two HTTP routers using the HostRegexp() matcher. It takes HTTP traffic from the entrypoint on port 80 and load balances it between two tunnels on ports 5080 and 5081.

The second pair of labels defines a TCP router that takes traffic from the HTTPS entrypoint on port 443, passes it through without decrypting, and load balances it between tunnels on ports 5443 and 5444. Note that with the HostSNIRegexp() matcher, you can't include escaped dots (.) in the regex, you must repeat the entire domain sequence to handle the www variant of the domain.

Also note that we use separate regex variants to match the root subdomain explicitly, e.g. pi.nemanjamitic.com and www.pi.nemanjamitic.com for both HTTP and TCP routers.

That's it, this is the main load balancing logic definition.

Note: Because we use HostRegexp() and HostSNIRegexp() on the server, you will need to use Host() and HostSNI() matchers for the Traefik running on the client side of the tunnel, or you will get 404 errors without additional configuration. Regex matchers on both the server and client sides seem to be too loose.

Rathole server config

Now it's just left to write the config for the Rathole server that defines 2×2 tunnels. Just make sure to use a different token and port for each tunnel.

# rathole.server.toml

[server]
bind_addr = "0.0.0.0:2333"

[server.transport]
type = "noise"

[server.transport.noise]
local_private_key = "private_key"

# separated based on token, also can NOT use same ports

# pi
[server.services.pi-traefik-http]
token = "secret_token_1"
bind_addr = "0.0.0.0:5080"

[server.services.pi-traefik-https]
token = "secret_token_1"
bind_addr = "0.0.0.0:5443"

# local
[server.services.local-traefik-http]
token = "secret_token_2"
bind_addr = "0.0.0.0:5081"

[server.services.local-traefik-https]
token = "secret_token_2"
bind_addr = "0.0.0.0:5444"

Reminder: You just need to open port 2333 in the VPS firewall for the Rathole control channel and not for the ports 5080, 5081, 5443, or 5444, because they are used by Rathole internally.

Traefik dashboard

Additionally, for the sake of debugging, we expose the Traefik dashboard using labels on the traefik container. To simplify the configuration and avoid handling the acme.json file, we expose it using HTTP.

Warning: When setting the dashboard hashed password via the TRAEFIK_AUTH environment variable, make sure to escape the $ characters properly or authentication will break. To do that, you need to use both double quotes "..." and the escape slash '\', as shown in the example below:

# install apache2-utils
sudo apt install apache2-utils

# hash the password
htpasswd -nb admin yourpassword

# .env

# use BOTH "..." and \$ to escape $ properly

# this will work correctly
TRAEFIK_AUTH="admin:\$asd1\$E3lsdAo\$3Mertp57JJ4LVU.HRR0"

# this will break
TRAEFIK_AUTH="admin:$asd1$E3lsdAo$3Mertp57JJ4LVU.HRR0"

# this will also break
TRAEFIK_AUTH=admin:\$asd1\$E3lsdAo\$3Mertp57JJ4LVU.HRR0

Rathole client

The client part of the tunnel is almost the same as for a single home server. The only thing to keep in mind is to bind the specific client only to the tunnels that are meant for it, and not to all tunnels. Kind of obvious and self-explanatory, but just in case, let's be very clear and explicit.

Here, we define the rathole.client.toml Rathole client config to bind the pi home server to its HTTP pi-traefik-http and HTTPS pi-traefik-https tunnels.

# rathole.client.toml

[client]
remote_addr = "123.123.123.123:2333"

[client.transport]
type = "noise"

[client.transport.noise]
remote_public_key = "public_key"

# single client per tunnels pair

# pi
[client.services.pi-traefik-http]
token = "secret_token_1"
local_addr = "traefik:80"

[client.services.pi-traefik-https]
token = "secret_token_1"
local_addr = "traefik:443"

Similarly, here we define the rathole.client.toml config to bind the local home server to it's HTTP local-traefik-http and HTTPS local-traefik-https tunnels.

# rathole.client.toml

[client]
remote_addr = "123.123.123.123:2333"

[client.transport]
type = "noise"

[client.transport.noise]
remote_public_key = "public_key"

# single client per tunnels pair

# local
[client.services.local-traefik-http]
token = "secret_token_2"
local_addr = "traefik:80"

[client.services.local-traefik-https]
token = "secret_token_2"
local_addr = "traefik:443"

docker-compose.yml for the Rathole client and Traefik is exactly the same as it was for a single home server. I am repeating it here just for the sake of completeness.

# docker-compose.yml

version: '3.8'

services:
  rathole:
    image: rapiz1/rathole:v0.5.0
    container_name: rathole
    command: --client /config/rathole.client.toml
    restart: unless-stopped
    volumes:
      - ./rathole.client.toml:/config/rathole.client.toml:ro
    networks:
      - proxy

  traefik:
    image: 'traefik:v2.9.8'
    container_name: traefik
    restart: unless-stopped
    depends_on:
      - rathole
    command:
      # moved from static conf to pass email as env var
      - '--certificatesresolvers.letsencrypt.acme.email=${TRAEFIK_LETSENCRYPT_EMAIL}'
    security_opt:
      - no-new-privileges:true
    networks:
      - proxy
    # rathole will pass traffic through proxy network directly on 80 and 443
    # defined in rathole.client.toml
    environment:
      - TRAEFIK_AUTH=${TRAEFIK_AUTH}
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik-data/traefik.yml:/traefik.yml:ro
      - ./traefik-data/acme.json:/acme.json
      - ./traefik-data/configurations:/configurations
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=proxy'
      - 'traefik.http.routers.traefik-secure.entrypoints=websecure'
      - 'traefik.http.routers.traefik-secure.rule=Host(`traefik.${SITE_HOSTNAME}`)'
      - 'traefik.http.routers.traefik-secure.middlewares=user-auth@file'
      - 'traefik.http.routers.traefik-secure.service=api@internal'

networks:
  proxy:
    external: true

Completed code

Traefik load balancer and Rathole server: https://github.com/nemanjam/rathole-server
Rathole client and local Traefik: https://github.com/nemanjam/traefik-proxy/tree/main/core

Conclusion

You can use this setup to expose as many home servers as you want, in a cost-effective and practical way, as long as your VPS has enough network bandwidth to support their traffic. It can bring your homelab to another level.

What tool and method did you use to expose your home servers to the internet? Do you like this approach, are you willing to give it a try? Let me know in the comments.

Happy self-hosting.

References

Traefik v2.9 HostRegexp reference: https://doc.traefik.io/traefik/v2.9/routing/routers/#rule
Traefik v2.9 HostSNIRegexp reference: https://doc.traefik.io/traefik/v2.9/routing/routers/#rule_1
TLS Server Name Indication (SNI), Wikipedia https://en.wikipedia.org/wiki/Server_Name_Indication

Expose home server with Rathole tunnel and Traefik

Nemanja Mitic — Thu, 01 May 2025 07:10:20 +0000

Introduction

In the previous article, I wrote about a temporary SSH tunneling technique to bypass CGNAT. This method is not suitable for exposing permanent services, at least not without autossh manager. Proper tools for this are rapiz1/rathole or fatedier/frp. I chose Rathole since it's written in Rust and offers better performance and benchmarks.

Prerequisites

A VPS server with a public IP and Docker, ideally small, you can't use ports 80 and 443 for any other services aside from Rathole
A home server
A domain name

Architecture overview

We will use Rathole for an encrypted tunnel between the VPS and the local network. We will also use Traefik since we want to host multiple websites on our home server, just like you would on any server.

The main question is where to run Traefik:

On the VPS
On the home server

I highly prefer option 2 because, that way, the entire configuration is stored on our home server. The home server is almost tunnel-agnostic, and you can reuse it on any tunneled or non-tunneled server. Otherwise, we would need to maintain state between the VPS and the home server, debug both together, etc.

Another point is that, with option 2, we avoid the gap of unencrypted traffic on the VPS between Traefik (TLS) and Rathole (Noise Protocol). You can read more about the comparison of these two options in this article: https://blog.mni.li/posts/caddy-rathole-zero-knowledge/.

The downside is that Rathole will exclusively occupy ports 80 and 443 on the VPS, preventing any other process from using them. We won't be able to run other web servers on that VPS, so it's best to use a small one dedicated to this purpose.

Unless we use a load balancer Load balancing multiple Rathole tunnels with Traefik HTTP and TCP routers.

Rathole server

We will run the Rathole server inside a Docker container on our VPS. Rathole uses the same binary for both the server and client, you just pass the right option (--server or --client) and the .toml configuration file.

Here is the Rathole server configuration rathole.server.toml:

# rathole.server.toml

[server]
bind_addr = "0.0.0.0:2333"

[server.transport]
type = "noise"

[server.transport.noise]
local_private_key = "private_key"

[server.services.traefik-http]
token = "secret_token_1"
bind_addr = "0.0.0.0:5080"

[server.services.traefik-https]
token = "secret_token_1"
bind_addr = "0.0.0.0:5443"

Let's explain it: we choose port 2333 for the control channel and bind it to all interfaces inside the Docker container with the 0.0.0.0 IP. We choose the noise encryption protocol and specify a private key. The public key will be used on the Rathole client. The public and private key pair is generated with:

docker run -it --rm rapiz1/rathole --genkey

Then we define two tunnels: one for HTTP and another for HTTPS. For the HTTP tunnel, we define the name server.services.traefik-http, set the value for token, and choose port 5080, and again we bind it to all container interfaces with 0.0.0.0. Similarly, for HTTPS, we set the name to server.services.traefik-https, provide a token value, and choose port 5443.

Every tunnel has to have a unique name, token value, and port. With that fulfilled, a single Rathole server instance can have as many Rathole clients as needed, which is pretty convenient. For example, besides the existing home server on ports 5080 and 5443, we can expose another one using ports 5081 and 5444.

Token is just a random base64 string, we generate it by running this:

openssl rand -base64 32

After configuration file we define a Rathole server container with docker-compose.yml:

# docker-compose.yml

services:
  rathole:
    image: rapiz1/rathole:v0.5.0
    container_name: rathole
    command: --server /config/rathole.server.toml
    restart: unless-stopped
    ports:
      # host:container
      - 2333:2333
      - 80:5080
      - 443:5443
    volumes:
      - ./rathole.server.toml:/config/rathole.server.toml:ro

In the command, we set the --server option, pass the .toml configuration file, and mount it as a read-only bind-mount volume.

The important part is the port mappings. Here, you can see that the Rathole server container will occupy ports 2333, 80, and 443 exclusively on the host VPS. This practically means we won't be able to run any other web servers on ports 80 and 443. We will also need to open ports 80, 443, and 2333 in the VPS firewall. You don't need to open ports 5080 and 5443, those are used only by Rathole internally.

Rathole client and connecting with Traefik

We run the Rathole client and Traefik inside Docker containers on the home server. Configuring the Rathole client and connecting it to Traefik is a bit more complex and tricky.

Here is the Rathole client configuration core/rathole.client.toml.example:

# core/rathole.client.toml.example

[client]
remote_addr = "123.123.123.123:2333"

[client.transport]
type = "noise"

[client.transport.noise]
remote_public_key = "public_key"

# this is the important part
# Rathole knows traffic comes from 5080 and 5443, control channel told him
# DON'T do ANY mapping in docker-compose.yml
# just pass traffic from Rathole on ports which Traefik expects (80 and 443)

[client.services.traefik-http]
token = "secret_token_1"
local_addr = "traefik:80"

[client.services.traefik-https]
token = "secret_token_1"
local_addr = "traefik:443"

Let's go through it. First, we define the VPS server IP remote_addr, the control channel port 2333, set the noise encryption protocol, and this time specify a public key remote_public_key.

Now comes the important and tricky part: defining tunnels and services. We repeat the service name and token that we used in the Rathole server config.

And now the most important part: local_addr, for this we target the Traefik hostname - service name from core/docker-compose.local.yml and the Traefik listening ports 80 and 443. That's it. It might look simple and obvious, this is the correct setup. I must emphasize: don't fall into temptation of setting any additional port mappings in core/docker-compose.local.yml, functionality will break, all should be done in core/rathole.client.toml.

Another note: You might wonder why ports 5080 and 5443 aren't repeated anywhere in the client config core/rathole.client.toml. The answer is "no need for it", we already specified port 2333 for the control channel, which will communicate all additional required information between the Rathole server and client.

Now that we have configured the Rathole client, we need to define Rathole client and Traefik containers.

Here is the Rathole client container and the important part of the Traefik container core/docker-compose.local.yml:

# core/docker-compose.local.yml

services:
  rathole:
    # 1. default official x86 image
    image: rapiz1/rathole:v0.5.0

    # 2. custom built ARM image (for Raspberry pi)
    # image: nemanjamitic/my-rathole-arm64:v1.0

    # 3. build for arm - AVOID, use prebuilt ARM image above
    # build: https://github.com/rapiz1/rathole.git#main
    # platform: linux/arm64

    container_name: rathole
    command: --client /config/rathole.client.toml
    restart: unless-stopped
    volumes:
      - ./rathole.client.toml:/config/rathole.client.toml:ro
    networks:
      - proxy

  traefik:
    image: 'traefik:v2.9.8'
    container_name: traefik
    restart: unless-stopped

    # for this to work both services must be defined in the same docker-compose.yml file
    depends_on:
      - rathole

    # other config...

    networks:
      - proxy

    # leave this commented out, just for explanation
    # Rathole will pass Traffic through proxy network directly on 80 and 443
    # defined in rathole.client.toml
    # ports:
    #   - '80:80'
    #   - '443:443'

    # other config...

Let's start with the Rathole service. Similarly to the server command, we run the Rathole binary, this time in client mode with --client and we pass the client config file /config/rathole.client.toml which we also bind mount as volume. An important part is that we set both the Rathole and Traefik containers on the same external network proxy so they can communicate with each other and with the host.

Additional notes about the Rathole image:

Always make sure to use the same Rathole image version for both the server and client for compatibility.
x86 - By default, Rathole provides only the x86 image. If your home server uses that architecture, you are good to go.
ARM - If you have an ARM home server (e.g., Raspberry Pi), you will have to build the image yourself or use a prebuilt, unofficial one. Avoid building images on low-power ARM single-board computers, as it will take a long time and require a lot of RAM and CPU power. Instead, either pre-build one yourself and push it to Docker Hub, or you can reuse my nemanjamitic/my-rathole-arm64:v1.0 image (which uses Rathole v0.5.0).

Now, the Traefik container. It must be on the same proxy external network as Rathole. Another important part: It must wait for the Rathole container to boot up depends_on: rathole, because the traffic will come from the Rathole tunnel. Do not expose ports 80 and 443, Rathole has already bound those Traefik container ports, as we defined in the Rathole client config core/rathole.client.toml.

The rest of the Traefik container definition is left out here because it's the usual configuration, unrelated to the Rathole tunnel. Below is a quick reminder about the general Traefik configuration.

Traefik reminder

Provide the .env file with variables needed for Traefik:

cp .env.example .env

# .env

SITE_HOSTNAME=homeserver.my-domain.com

# important: must put value in quotes "..." and escape $ with \$
TRAEFIK_AUTH=

# will receive expiration notifications
TRAEFIK_LETSENCRYPT_EMAIL=myname@example.com

On your home server host OS you must create an external Docker network:

docker network create proxy

Create acme.json file with permission 600:

touch ~/homelab/traefik-proxy/core/traefik-data/acme.json

sudo chmod 600 ~/homelab/traefik-proxy/core/traefik-data/acme.json

Always start with the staging Acme server for testing and swap to production once satisfied:

# core/traefik-data/traefik.yml

certificatesResolvers:
  letsencrypt:
    acme:
      # always start with staging certificate
      caServer: 'https://acme-staging-v02.api.letsencrypt.org/directory'
      # caServer: 'https://acme-v02.api.letsencrypt.org/directory'

To clear the temporary staging certificates, clear the contents of acme.json

truncate -s 0 acme.json

That's it. Once done, we can run Rathole client and Traefik containers on our home server with:

docker compose -f docker-compose.local.yml up -d

Exposing multiple servers

Fortunately, Rathole makes it trivial to run multiple tunnels using a single Rathole server. We don't need to open any additional ports in the firewall or run multiple container instances. What we do need are different tunnel names, token values, and ports. Those must be unique for each tunnel/service. Also, you will need a load balancer to bind ports 80 and 443 to more than one destination port, respectively.

I wrote a detailed tutorial on how to expose multiple home servers using a single Rathole server. You can read it here: Load balancing multiple Rathole tunnels with Traefik HTTP and TCP routers.

Open the firewall on the VPS

Like for any webserver, on the VPS you will need to open ports 80 and 443 to listen for HTTP/HTTPS traffic. Additionally you will need to open the port 2333 for the Rathole control channel - tunnel.

Completed code

Rathole server: https://github.com/nemanjam/rathole-server
Rathole client and local Traefik: https://github.com/nemanjam/traefik-proxy/tree/main/core

Conclusion

Most consumer-grade internet connections are behind a CGNAT. This setup allows you to bypass CGNAT and host an unlimited number of websites on your home server almost for free. You can use it for web servers in virtual machines, LXC containers, SBC computers, etc. - anywhere you can run Docker.

It is simple, cheap, and you can set it up in 30 minutes. Like anything, it also has some downsides, one of them is the overhead latency caused by an additional network hop between the VPS and your home network, but it's a reasonable tradeoff.

Did you make something similar yourself? Can you see room for improvement? Did you use a different method? You tried to run the code and need help with troubleshooting? Let me know in the comments.

References

Rathole repository https://github.com/rapiz1/rathole
Local or remote Traefik discussion https://github.com/rapiz1/rathole/issues/169
Local and remote Traefik comparison, Tailscale benchmarks https://blog.mni.li/posts/caddy-rathole-zero-knowledge/
Rathole Docker example configuration https://nitinja.in/tech/
Rathole .toml environment variables discussion https://github.com/rapiz1/rathole/issues/218
frp repository https://github.com/fatedier/frp

Expose local dev server with SSH tunnel and Docker

Nemanja Mitic — Wed, 23 Apr 2025 09:44:06 +0000

Introduction

Most consumer-grade internet connections are hidden behind CG-NAT and are not reachable from the internet. This is done to save IP addresses, as IPv4 has a limited range. If you have a static public IPv4 or any IPv6 address, you won’t need the setup from this tutorial.

There are already services like localtunnel or ngrok for this purpose, but when you actually start using them, you will often find out that they have limitations on their free plans. So, we will configure our own custom setup once and have it always available for convenient and practical usage which will save a lot of time and nerves in the long run.

Why is this useful

This is useful whenever you need to share your local project with others or provide a publicly accessible URL for your service so that external systems can reach it. This is often the case if you work remotely.

Yes, you can use test deployments, but having a tunnel setup configured and being able to run it with a single terminal command saves a lot of time and energy.

Possible use cases:

Sharing work in progress with clients or teammates
Remote debugging or pair programming
Demos for presentations or team meetings
Testing the frontend on different devices (mobile, different resolution, OS, browser)
Testing webhooks from external services (Stripe, GitHub, Oauth, Slack, Contentful, Twilio, etc.)

Prerequisites

A VPS server with a public IP and Docker
A local machine with a working SSH and dev server that you want to expose
A domain name (optional)

Demo video

Architecture overview

Without going too deep into computer networking theory, let's explain port forwarding in simplified terms. Port forwarding is a mapping (binding) between two points (services) on a private network (or even on the same machine) that would otherwise be unreachable. You can think of it as a VPN for a single service (port).

So it's exactly what we need: we want to bind (redirect traffic from) a public port (1081 in our case) on the VPS, which acts as a gateway, to port 3000 on our local dev server that is not directly reachable from the internet. That’s it for the tunneling part, this setup is sufficient for serving HTTP traffic.

Additionally, to support HTTPS and provide a user-friendly URL, we will add Traefik, which will handle HTTPS certificates and route traffic from port 443 to port 1081 of the tunnel.

Running the SSH server in Docker

We already use SSH to access our VPS, but we prefer to keep that configuration untouched. So, we will run a separate SSH server inside a Docker container specifically for tunneling.

For this, we will use linuxserver/openssh-server image. Linuxserver is an organization that maintains very stable Dokcer images for all kinds of purposes.

By default, the SSH server doesn’t allow tunneling, so we need to modify the config in /etc/ssh/sshd_config and enable it.

# /etc/ssh/sshd_config

AllowTcpForwarding yes
GatewayPorts yes

sudo nano /etc/ssh/sshd_config

# edit config...

sudo systemctl restart sshd

But since we are using a Docker container, we will do it differently.

We will use openssh-server-ssh-tunnel mod, which enables tunnelling in the linuxserver/openssh-server image. You can think of mods as presets (additional layers and configurations) for these images.

Here is docker-compose.yml for the SSH tunnel container:

# docker-compose.yml

version: '3.8'

services:
  openssh-server:
    image: linuxserver/openssh-server
    container_name: openssh-server
    restart: unless-stopped
    hostname: openssh-server #optional
    expose:
      - 1081 # tunneled service port, for Traefik
    ports:
      - 1080:2222 # 1080 is the main SSH connection port
    environment:
      # https://github.com/linuxserver/docker-mods/tree/openssh-server-ssh-tunnel
      - DOCKER_MODS=linuxserver/mods:openssh-server-ssh-tunnel
      - SHELL_NOLOGIN=false
      # set correct for current host user
      - PUID=1001
      - PGID=1001
      - TZ=Etc/UTC
      # important
      - PUBLIC_KEY
      # optional env vars bellow
      - SUDO_ACCESS=true
      - USER_NAME=username
      - PASSWORD_ACCESS=false
    volumes:
      - ./config:/config
    # Traefik configuration bellow
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=proxy'
      - 'traefik.http.routers.ssh-tunnel.rule=Host(`preview.${SITE_HOSTNAME}`)'
      - 'traefik.http.routers.ssh-tunnel.entrypoints=websecure'
      - 'traefik.http.routers.ssh-tunnel.service=ssh-tunnel'
      - 'traefik.http.services.ssh-tunnel.loadbalancer.server.port=1081' # matches exposed port
    networks:
      - proxy

networks:
  proxy:
    external: true

Lets explain the code above:

services:
  openssh-server:
    image: linuxserver/openssh-server
    # ...
    ports:
      - 1080:2222 # 1080 is the main SSH connection port

By default, linuxserver/docker-openssh-server runs the SSH service on port 2222, to avoid conflicting with the usual port 22 that is used for host's SSH service and it's hardcoded in the Dockerfile. We will choose port 1080 for the main SSH connection, so we need to map it to port 2222 with SSH in the container. Port 1080 is used for the actual connection over the internet, and it is required to allow that port in VPS firewall.

So, let's establish clear and precise naming from the beginning:

Port 1080 - the main SSH connection port
Ports 1081, 1082, 1083, ... - tunneled services remote ports

Additionally, you need to configure the SSH client on your dev machine to use port 1080 for SSH when connecting to this container. In this example I have named VPS host amd1 and SSH container host amd1c, you can use your own naming logic.

# ~/.ssh/config

# ssh amd1 ssh container
Host amd1c 123.123.123.123 # VPS IP
    HostName 123.123.123.123
    IdentityFile ~/.ssh/my-keys/amd1_ssh_container__id_ed25519 # private key file name
    User username
    Port 1080

In the client SSH config above, you will notice the private key file amd1_ssh_container__id_ed25519. The public key is passed to the SSH container as an environment variable:

services:
  openssh-server:
    image: linuxserver/openssh-server
    # ...
    environment:
      - PUBLIC_KEY # important

You generate SSH key pairs as usual, e.g.:

ssh-keygen -t ed25519 -C "myemail@gmail.com" -f ~/.ssh/my-keys/amd1_ssh_container__id_ed25519

Now, we choose which remote port we will use to expose our local dev server. If you're using Traefik and don’t access this port directly via the browser, you don’t need to allow it in the VPS's firewall.

services:
  openssh-server:
    image: linuxserver/openssh-server
    # ...
    expose:
      - 1081 # tunneled service remote port

The other environment variables worth mentioning are the following:

services:
  openssh-server:
    image: linuxserver/openssh-server
    # ...
    environment:
      # https://github.com/linuxserver/docker-mods/tree/openssh-server-ssh-tunnel
      - DOCKER_MODS=linuxserver/mods:openssh-server-ssh-tunnel
      - PUID=1001
      - PGID=1001

We use DOCKER_MODS variable to specify openssh-server-ssh-tunnel mod. PUID and PGID are user and group IDs used to handle permissions between the host and the container. You get their values by running id -u && id -g on the VPS host. It is also a good idea to export them as global environment variables in ~/.bashrc file to make them available for all containers:

# ~/.bashrc

export MY_UID=$(id -u)
export MY_GID=$(id -g)

Then you can pass them like this:

# docker-compose.yml

# ...
environment:
  - PUID=$MY_UID
  - PGID=$MY_GID

The SSH tunnel is now configured. Now you can access your local dev server by HTTP via the your VPS IP e.g. http://123.123.123.123:1081 or domain http://my-domain.com:1081.

Configuring HTTPS with Traefik

Some browsers disallow insecure HTTP traffic by default, and you need to tweak the browser settings to allow it explicitly. This can be inconvenient when sending a demo link to a non-technical person. Additionally, some OAuth providers require HTTPS even for testing (e.g. Facebook). So let's make an extra effort to do things properly and configure a HTTPS with a subdomain using Traefik.

If you are running a VPS, chances are you already use a reverse proxy for handling certificates and subdomain routing. This example shows how to do it with Traefik.

# docker-compose.yml

services:
  openssh-server:
    image: linuxserver/openssh-server
    container_name: openssh-server
    # ...
    expose:
      - 1081 # tunneled service remote port
    ports:
      - 1080:2222 # 1080 is the main SSH connection port

    # Traefik configuration bellow
    labels:
      - 'traefik.enable=true'
      - 'traefik.docker.network=proxy'
      - 'traefik.http.routers.ssh-tunnel.rule=Host(`preview.${SITE_HOSTNAME}`)'
      - 'traefik.http.routers.ssh-tunnel.entrypoints=websecure'
      - 'traefik.http.routers.ssh-tunnel.service=ssh-tunnel'
      - 'traefik.http.services.ssh-tunnel.loadbalancer.server.port=1081' # matches exposed port
    networks:
      - proxy

networks:
  proxy:
    external: true

The truth is, there is not much work to do here. All you need to do is to map the remote port of the tunnel 1081 to Traefik and define the URL on which you want to expose your local dev server via the environment variable e.g. SITE_HOSTNAME=preview.my-domain.com.

Everything else is just generic Traefik configuration. Also, don't forget to add the wildcard A record for your subdomains (e.g., you might add a *.tunnels "namespace") in your DNS provider's dashboard and point it to your VPS IP. Additionally, create an external Docker network, e.g. named proxy as shown in the example above.

services:
  openssh-server:
    image: linuxserver/openssh-server
    container_name: openssh-server
    # ...
    expose:
      - 1081 # tunneled service remote port, passed to Traefik

    # ...
    # Traefik configuration bellow
    labels:
      # ...
      - 'traefik.http.routers.ssh-tunnel.rule=Host(`preview.${SITE_HOSTNAME}`)' # in .env file: SITE_HOSTNAME=my-domain.com
      - 'traefik.http.services.ssh-tunnel.loadbalancer.server.port=1081' # matches the exposed port

In the end, you just need to define 2 environment variables for your docker-compose.yml inside the .env file:

# .env

# full with subdomain, without 'https://'
SITE_HOSTNAME=my-domain.com # or e.g. preview.my-domain.com

# public ssh key
PUBLIC_KEY=my-public-ssh-key

Above is shown only the relevant Traefik configuration for the SSH tunnel container. A complete Traefik reverse proxy configuration requires additional static and dynamic configurations for the Traefik container, but that is outside the scope of this tutorial. You can search for examples of Traefik configurations or reuse mine, which is available in this repository: nemanjam/traefik-proxy.

Tunneling multiple services

Sometimes your app runs more than a single service, e.g. frontend and backend. If you expose just the frontend from port 3000, note that localhost from, e.g. localhost:5000 won't be resolved. Therefore, you need to tunnel all services and set the tunneled URLs in your .env files.

How to have more than one tunnel? Your first thought might be to run multiple SSH server containers, but fortunately, that is not necessary. You can tunnel as many services as you want through a single SSH connection. You just need to expose multiple ports on the SSH container and map them to multiple Traefik hosts with labels, as shown below:

# docker-compose.yml

version: '3.8'

services:
  openssh-server:
    image: linuxserver/openssh-server
    container_name: openssh-server
    restart: unless-stopped
    hostname: openssh-server #optional
    # tunneled services, remote ports
    expose:
      - 1081 # tunnel1
      - 1082 # tunnel2
      - 1083 # tunnel3
    ports:
      - 1080:2222 # 1080 is the main SSH connection port
    environment:
      # https://github.com/linuxserver/docker-mods/tree/openssh-server-ssh-tunnel
      - DOCKER_MODS=linuxserver/mods:openssh-server-ssh-tunnel
      - SHELL_NOLOGIN=false
      # set correct for current host user
      - PUID=1001
      - PGID=1001
      - TZ=Etc/UTC
      # important
      - PUBLIC_KEY
      # optional env vars bellow
      - SUDO_ACCESS=true
      - USER_NAME=username
      - PASSWORD_ACCESS=false
    volumes:
      - ./config:/config
    # Traefik configuration bellow
    labels:
      # common config
      - 'traefik.enable=true'
      - 'traefik.docker.network=proxy'

      # tunnel1 (port 3000 -> 1081)
      - 'traefik.http.routers.ssh-tunnel1.rule=Host(`preview1.${SITE_HOSTNAME}`)'
      - 'traefik.http.routers.ssh-tunnel1.entrypoints=websecure'
      - 'traefik.http.routers.ssh-tunnel1.service=ssh-tunnel1'
      - 'traefik.http.services.ssh-tunnel1.loadbalancer.server.port=1081'

      # tunnel2 (port 5000 -> 1082)
      - 'traefik.http.routers.ssh-tunnel2.rule=Host(`preview2.${SITE_HOSTNAME}`)'
      - 'traefik.http.routers.ssh-tunnel2.entrypoints=websecure'
      - 'traefik.http.routers.ssh-tunnel2.service=ssh-tunnel2'
      - 'traefik.http.services.ssh-tunnel2.loadbalancer.server.port=1082'

      # tunnel3 (port 5001 -> 1083)
      - 'traefik.http.routers.ssh-tunnel3.rule=Host(`preview3.${SITE_HOSTNAME}`)'
      - 'traefik.http.routers.ssh-tunnel3.entrypoints=websecure'
      - 'traefik.http.routers.ssh-tunnel3.service=ssh-tunnel3'
      - 'traefik.http.services.ssh-tunnel3.loadbalancer.server.port=1083'

    networks:
      - proxy

networks:
  proxy:
    external: true

If you have a large number of services to tunnel, you might want to use a VPN to access all ports by default, but that's rarely the case.

Another point to make is that the SSH tunnel technique is most suitable for temporarily exposing services for demo purposes. For permanent tunnels, you would need to add autossh to keep the connection alive, but there are better tools for permanent tunnels, such as rapiz1/rathole or fatedier/frp.

Open the firewall on the VPS

For the main SSH connection, you will need to open a port in your VPS firewall, port 1080 in this example. Additionally, if you want to access tunnels directly via a port in the browser without Traefik, you will need to open those ports as well. Be mindful not to open too many unnecessary ports, as every newly opened port increases the attack surface.

Running the tunnel

You start the tunnel with a single command like below. The -R option means remote port forwarding, followed by two IP:port pairs. The first pair is remote, and the second is local. At the end, you have the VPS host.

# command format
ssh -R [remote_addr:]remote_port:local_addr:local_port [user@]gateway_addr

# example:
# amd1c host is defined in ~/.ssh/config
ssh -R *:1081:localhost:3000 amd1c

# access the url, e.g.
https://preview1.my-domain.com

# terminate tunnel, like any ssh connection
exit

You can open multiple tunnels with a single command. Just specify the tunnels one after another before the host. Note that you must have these tunnels defined in your docker-compose.yml for the SSH server (exposed ports and Traefik host labels).

# tunnel frontend at port 3000 and backend at port 5000
ssh \
  -R *:1081:localhost:3000 \
  -R *:1082:localhost:5000 \
  amd1c

# access the urls, e.g.
https://preview1.my-domain.com
https://preview2.my-domain.com/api

Completed code

SSH tunnel configuration: https://github.com/nemanjam/traefik-proxy/tree/main/apps/ssh-server
Traefik configuration: https://github.com/nemanjam/traefik-proxy/tree/main/core

Conclusion

Port forwarding is a basic networking technique that is very familiar to network engineers, but perhaps not often utilized by developers. It can be very useful and practical, especially in a remote work setting. As described in this tutorial, you just need to run a single container, configure the client and firewall, and once you have it set up, it can save you a lot of time and energy in the long run.

SSH remote port forwarding is just one of the many useful and cool SSH networking tricks. There are many others like dynamic port forwarding, SSH agent forwarding, X11 forwarding, SSH file system, etc. Do you use some of them? Please share in the comments bellow.

References

Local and remote port forwarding tutorial https://iximiuz.com/en/posts/ssh-tunnels
linuxserver/docker-openssh-server image repository https://github.com/linuxserver/docker-openssh-server
openssh-server-ssh-tunnel mod repository https://github.com/linuxserver/docker-mods/tree/openssh-server-ssh-tunnel
Useful discussion that suggests to use the existing tunnel mod https://github.com/linuxserver/docker-openssh-server/issues/22
The list of all available Linuxserver mods https://github.com/linuxserver/docker-mods, https://mods.linuxserver.io
The list of all available Linuxserver images https://www.linuxserver.io/our-images

Build a random image component with Astro and React

Nemanja Mitic — Wed, 09 Apr 2025 09:59:16 +0000

Introduction

For the sake of practice and fun let's build a component that displays a random image on mouse click. It looks more fun and interactive than a static hero image. You can see it in action on the Home page of the my website.

This functionality shares some common parts with the image gallery described in the previous article, such as the component hierarchy and including urls in the client. However, it also introduces some new elements, like a proper blur preloader.

What we will be building

Demo: https://nemanjamitic.com/
Github repository: https://github.com/nemanjam/nemanjam.github.io

Component hierarchy

Again, we will use the similar structure MDX (index.mdx) -> Astro component (ImageRandom.astro) -> React components (ImageRandomReact.jsx and ImageBlurPreloader.jsx), and again, the client React components contain the most complexity.

Code (paraphrased):

// src/pages/index.mdx

<ImageRandom />

// src/components/ImageRandom.astro

<ImageRandomReact {galleryImages} client:load />

// src/components/react/ImageRandomReact.tsx

<ImageBlurPreloader {...props} />

Responsive image

This is the functionality shared with the image gallery. This time, we’ll use a fixed low-resolution image for the blur effect and a responsive, high-resolution hero image as the main one. The blur and main images will have different resolutions but share the same 16:9 aspect ratio.

The code is as follows:

// src/constants/image.ts

export const IMAGE_SIZES = {
  FIXED: {
    // blur image
    BLUR_16_9: {
      width: 64,
      height: 36,
    },
  // ...
  },
  RESPONSIVE: {
    // main image
    POST_HERO: {
      widths: [TW_SCREENS.XS, TW_SCREENS.SM, TW_SCREENS.MD, TW_SCREENS.LG],
      sizes: `(max-width: ${TW_SCREENS.XS}px) ${TW_SCREENS.XS}px, (max-width: ${TW_SCREENS.SM}px) ${TW_SCREENS.SM}px, (max-width: ${TW_SCREENS.MD}px) ${TW_SCREENS.MD}px, ${TW_SCREENS.LG}px`,
    },
    // ...
  },
};

// actual <img /> tag attributes that are generated with the POST_HERO

<img
  sizes="(max-width: 475px) 475px, (max-width: 640px) 640px, (max-width: 768px) 768px, 1024px"
  width="3264"
  height="1836"
  srcset="
    /_astro/amfi1.Cv2xkJ5B_1Lofkq.webp 475w,
    /_astro/amfi1.Cv2xkJ5B_Oxmi8.webp 640w,
    /_astro/amfi1.Cv2xkJ5B_X0wXS.webp 768w,
    /_astro/amfi1.Cv2xkJ5B_Z1u01H4.webp 1024w
  "
  src="/_astro/amfi1.Cv2xkJ5B_26HGs8.webp"
/>

// src/libs/gallery/transform.ts

export const heroImageOptions = {
  ...IMAGE_SIZES.RESPONSIVE.POST_HERO,
};

// src/libs/gallery/images.ts

export const getHeroImages = async (): Promise<HeroImage[]> => {
  const blur = await getCustomImages(blurImageOptions);
  const hero = await getCustomImages(heroImageOptions);

  const heroImages = mergeArrays(blur, hero).map(([blur, hero]) => ({
    blur: imageResultToImageAttributes(blur),
    hero: imageResultToImageAttributes(hero),
  }));

  return heroImages;
};

// src/components/ImageRandom.astro

const galleryImages = await getHeroImages();

Responsive main image in action:

Random image in a static website

Again, we have the same situation as in the image gallery. The key point is to include all image urls in the client and execute getRandomElementFromArray() in the client React component to display a random image at runtime. If we called the random function on the server, in the Astro component, we would end up with a single image that was randomly picked at build time - which is not what we want.

This is the code:

---
// src/components/ImageRandom.astro

const galleryImages = await getHeroImages();
---

{/* include all the images in the client and let the client pick the random image */}

<div  {...props}>
  <ImageRandomReact {galleryImages} client:load />
</div>

// src/components/react/ImageRandom.tsx

const ImageRandomReact: FC<Props> = ({ galleryImages, className, divClassName, ...props }) => {
  // cache randomized images
  const randomImage = useMemo(() => getRandomElementFromArray(galleryImages), [galleryImages]);

  const [image, setImage] = useState(initialImage);

  // pick initial random image on mount
  useEffect(() => {
    setImage(randomImage);
  }, [setImage, randomImage]);

  // pick random image onClick
  const handleClick = async () => {
    const randomImage = getRandomElementFromArray(galleryImages);
    setImage(randomImage);
  };

  return (
    <ImageBlurPreloader
      {...props}
      blurAttributes={{ ...image.blur, alt: 'Blur image' }}
      mainAttributes={{ ...image.hero, onClick: handleClick, alt: 'Hero image' }}
      className={cn('cursor-pointer my-0', className)}
      divClassName={divClassName}
    />
  );
};

Blur preloader

This is the most interesting part of the feature. The first instinct when swapping the blur and main images might be to use a ternary operator to mount or unmount the appropriate image. But we actually can’t do that here. Why? Because both images need to remain mounted in the DOM to ensure the onLoad event works correctly for both the blur and main images. So instead of unmounting, we will use absolute positioning to place the main image above the blur image and toggle its opacity to show or hide it.

But there is more. Note that with the onLoad event, we have three possible values for the image’s src attribute (although the main image actually uses the srcset and sizes attributes). These are:

An empty string '' when both blur and main images are still loading. In this case we will show an empty <div /> of the same size as the main image.
The src attribute of the blur image, when the blur image is loaded but the main image is still loading.
The srcset and sizes attributes of the main image, once the main image has fully loaded.

This is the code src/components/react/ImageBlurPreloader.tsx:

// src/components/react/ImageBlurPreloader.tsx

const initialAttributes: ImgTagAttributes = { src: '' } as const;

const ImageBlurPreloader: FC<Props> = ({
  blurAttributes = initialAttributes,
  mainAttributes = initialAttributes,
  onMainLoaded,
  className,
  divClassName,
}) => {
  const [isLoadingMain, setIsLoadingMain] = useState(true);
  const [isLoadingBlur, setIsLoadingBlur] = useState(true);

  const prevMainAttributes = usePrevious(mainAttributes);

  const isNewImage = !(
    prevMainAttributes?.src === mainAttributes.src &&
    prevMainAttributes.srcSet === mainAttributes.srcSet
  );

  // reset isLoading on main image change
  useEffect(() => {
    if (isNewImage) {
      setIsLoadingBlur(true);
      setIsLoadingMain(true);
    }
  }, [isNewImage, setIsLoadingMain, setIsLoadingBlur]);

  // important: main image must be in DOM for onLoad to work
  // unmount and display: none; will fail
  const handleLoadMain = () => {
    setIsLoadingMain(false);
    onMainLoaded?.();
  };

  const commonAttributes = {
    // blur image must use size from main image
    width: mainAttributes.width,
    height: mainAttributes.height,
  };

  const blurAlt = !isLoadingBlur ? blurAttributes.alt : '';
  const mainAlt = !isLoadingMain ? mainAttributes.alt : '';

  const hasImage = Boolean(
    isLoadingMain
      ? mainAttributes.src || mainAttributes.srcSet
      : blurAttributes.src || blurAttributes.srcSet
  );

  return (
    <div className={cn('relative size-full', divClassName)}>
      {hasImage && (
        <>
          {/* blur image */}
          <img
            {...blurAttributes}
            {...commonAttributes}
            alt={blurAlt}
            onLoad={() => setIsLoadingBlur(false)}
            className={cn('object-cover absolute top-0 left-0 size-full', className)}
          />

          {/* main image */}
          <img
            {...mainAttributes}
            {...commonAttributes}
            alt={mainAlt}
            onLoad={handleLoadMain}
            className={cn(
              'object-cover absolute top-0 left-0 size-full',
              // important: don't hide main image until next blur image is loaded
              isLoadingMain && !isLoadingBlur ? 'opacity-0' : 'opacity-100',
              className
            )}
          />
        </>
      )}
    </div>
  );
};

That is a lot of code, so let’s break it down. First, note the use of relative and absolute classes to position the images on top of each other.

We set the initial src to an empty string in the initialAttributes variable. This sets the hasImage flag to true, unmounts the images, and displays an empty <div> that fills the parent container thanks to the size-full class (which is needed to prevent layout shift).

Next, note that we track the separate states isLoadingMain and isLoadingBlur for the main and blur images. Both are necessary so we can correctly show/hide the main image by changing its opacity from opacity-0 to opacity-100. The general idea is this: "Always keep the blur image below, just show or hide the main image above."

Additionally, we track the previous main image, prevMainAttributes, to detect when a new image is selected via the onClick event passed from the parent component.

Finally, while an image is loading, we set its alt attribute (using the blurAlt and mainAlt variables) to an empty string to avoid rendering text in place of an empty image, as it doesn't look nice.

Bonus tip: You can also experiment with the <img style={{imageRendering: 'pixelated'}} /> scaling style on the blur image if you find it more aesthetically pleasing.

Cumulative layout shift

This is also an interesting part. In general, the server always sends images with their sizes (at least it should), which makes handling layout shifts easier, so we should be able to solve it properly.

The key point is this: Set the component's actual size in the server component ImageRandom.astro and use w-full h-full (size-full) in the client ImageRandom.tsx React component to stretch it to fill the parent. This way, the size is resolved on the server, and there is no shift when hydrating the client component.

Lets see it in practice src/components/ImageRandom.astro#L21

// src/components/ImageRandom.astro"

---
// add 'px' suffix or styles will fail
const { width, height } = Object.fromEntries(
  Object.entries(IMAGE_SIZES.FIXED.MDX_XL_16_9).map(([key, value]) => [key, `${value}px`])
);
---

{/* height and width MUST be defined ON SERVER component to prevent layout shift */}
{/* set height and width to image size but set real size with max-height and max-width */}

<div
  class={cn('max-w-full max-h-64 md:max-h-96 my-8', className)}
  style={{ width, height }}
  {...props}
>
  <ImageRandomReact {galleryImages} client:load />
</div>

We use the max-w-... and max-h-... classes to set the actual (responsive) size for the server component, which the client component will fill.

The my-8 margin is there to override the vertical margin styles for the image component in the markdown (prose class). Remember, we have two actual, absolutely positioned <img /> tags in the DOM, so prose will add double margins, and we need to correct that.

Client component src/components/react/ImageBlurPreloader.tsx:

// src/components/react/ImageBlurPreloader.tsx

const ImageBlurPreloader: FC<Props> = ({
  // ...
  className,
  divClassName,
}) => {
  // ...

  return (
    <div className={cn('relative size-full', divClassName)}>
      {hasImage && (
        <>
          {/* blur image */}
          <img className={cn('object-cover absolute top-0 left-0 size-full', className)} />

          {/* main image */}
          <img className={cn('object-cover absolute top-0 left-0 size-full')} />
        </>
      )}
    </div>
  );
};

In the client component, we simply stretch all elements with size-full to fill the parent server component.

With this in place, we achieve the following score for the cumulative layout shift:

Completed code and demo

Demo: https://nemanjamitic.com/
Github repository: https://github.com/nemanjam/nemanjam.github.io

The relevant files:

# https://github.com/nemanjam/nemanjam.github.io/tree/c1e105847d8e7b4ab4aaffad3078726c37f67528
git checkout c1e105847d8e7b4ab4aaffad3078726c37f67528

# random image code
src/pages/index.mdx
src/components/ImageRandom.astro
src/components/react/ImageRandom.tsx
src/components/react/ImageBlurPreloader.tsx

# common code with gallery
src/libs/gallery/images.ts
src/libs/gallery/transform.ts
src/constants/image.ts

Outro

Once again, we played around with images, Astro, and React. Have you implemented any similar components yourself, maybe a carousel? What was your approach? Do you have suggestions for improvements or have you spotted anything incorrect? Don’t hesitate to leave a comment below.

References

React image preloader tutorial https://benhoneywill.com/progressive-image-loading-with-react-hooks/
Astro documentation, tutorial how to use getImage() function https://docs.astro.build/en/recipes/build-custom-img-component/
"Squared" image scaling algorithm styles https://www.w3schools.com/cssref/css3_pr_image-rendering.php

Build an image gallery with Astro and React

Nemanja Mitic — Tue, 08 Apr 2025 08:33:36 +0000

Introduction

I wanted to have a simple, Instagram-like, scroll paginated gallery page on the website where I could share my everyday photos. Initially I implemented it using benhowell/react-grid-gallery package for gallery, and frontend-collective/react-image-lightbox for lightbox component. It worked ok, but since those are a bit legacy packages I was unable to upgrade to React 19, it loaded all images at once without scroll pagination and Lighthouse score wasn't so great.

You can see that implementation if you navigate back in Git history e0165b:

# in git history navigate back to the old gallery commit
git checkout e0165b295db2ccc72bbbb7be4bdd7eb48f7dedae

# preview
yarn clean && yarn install && yarn dev

I decided to reimplement it, did a quick research and decided to make my own gallery component and use dimsemenov/photoswipe package for lightbox. And that's how this article got created, while implementing I took notes about the most important and interesting parts from the process. Look at it as not necessarily the absolute best way to make image gallery with Astro and React but as one of the ways that is proven in practice and works well.

What we will be building

Demo: https://nemanjamitic.com/gallery
Github repository: https://github.com/nemanjam/nemanjam.github.io

Image - server component, client component, slot, props

This is the first dilemma and initial decision that affects all the future code that we write. Since this is a static website example we are naturally inclined to pre-render everything we can at build time, but can this work for images too?

Astro provides <Image /> component and it's a server component like any other Astro component. It is clear that we will need onLoad, onClick events on a image and events aren't possible on a server component. Yes, but maybe we can use client component wrapper and pass Astro <Image /> component as a slot so we can have best from both - Astro component for image optimization and a <div /> for events, could this work?

Not really, for any preload effects onLoad event needs to be on the <img /> tag, but more important is that we can't pass any client props to the slot <Image /> component, we can generate only a single instance at build time. For any props values we would need to pregenerate separate image HTML which in this case is highly impractical.

Conclusion: We will use a React client component that supports interactivity and Astro getImage() function to optimize the images.

API route vs `import.meta.glob()`

We want to stick to a static website, for performance reasons and convenient deployments. What way should we use to pass the image urls to the client? We could make a static API endpoint that serves JSON array. We could even make an parametrized API endpoint that serves optimized images.

Right away, why having an extra HTTP call for JSON on client when we can pregenerate image urls at build time, it's not what we want.

For a static API endpoint, since it's static we would need to pre-render all params at build time, so we could do http://localhost/api/gallery/xl/image1.webp but not http://localhost/api/gallery/300x200/image1.webp and http://localhost/api/gallery/301x200/image1.webp, for that we would need to enable Astro server side rending and have Node.js runtime in production.

If we log a src attribute of an imported image in dev and prod mode we will see something like this:

// in dev
http://localhost:3000/_image?href=/@fs/home/username/Desktop/nemanjam.github.io/src/assets/images/all-images/morning1.jpg?origWidth=4608&origHeight=2592&origFormat=jpg&w=1280&h=720&f=webp

// in prod
http://localhost:3000/_astro/morning1.CEdGhKb3_nVk9T.webp

So Astro is already serving images for us, with a dedicated API endpoint we would just accomplish human friendly url rewriting, that could be useful only if some external service fetches those images, which we don't have here.

Conclusion: We will use import.meta.glob('/src/assets/images/all-images/*.jpg') from Vite to import images as modules to obtain images at build time and pass them as props into the Gallery component.

The code is as follows src/libs/gallery/images.ts#L16:

// src/libs/gallery/images.ts

export const getGalleryImagesMetadata = (): ImageMetadata[] => {
  const imageModules = import.meta.glob<{ default: ImageMetadata }>(
    // can't be a variable
    '/src/assets/images/all-images/*.jpg',
    { eager: true }
  );

  // convert map to array
  const imagesMetadata = Object.keys(imageModules)
    // filter excluded filenames
    .filter((path) => !EXCLUDE_IMAGES.some((excludedFileName) => path.endsWith(excludedFileName)))
    // return metadata array
    .map((path) => imageModules[path].default);

  return imagesMetadata;
};

Code structure

We will structure code like this: MDX (gallery.mdx) -> Astro component (Gallery.astro) -> React component (Gallery.jsx). The call stack is top-down, MDX is a declarative presentation layer, Astro component will resolve data - images, React component will handle events and define logic, it's the most complex layer.

Code (paraphrased):

// src/pages/gallery.mdx

<Gallery class="not-prose grow" />

// src/components/Gallery.astro

<ReactGallery client:only="react" images={randomizedGalleryImages} />

// src/components/react/Gallery.tsx

<div className="grid grid-cols-1 gap-1 sm:grid-cols-2 lg:grid-cols-3">
  {loadedImages.map((image) => (
    <img {...imageProps} />
  )}
</div>

Static generation, include image urls and `map()` on the client

Again, interesting and important point that is easy to forget is that images.map() needs to be in React component in order to have infinite scroll pagination. For that all image urls (and other props) need to be bundled and available on client, that is passed as props from Astro to the React component.

If we placed images.map() in the Astro component we would we would have a single image list as is without any interactivity (pagination on scroll).

Reminder: Static "backend" runs only once - at build time. We have a Node.js runtime only in development, and not in production - in there we have just a webserver static folder for serving assets. Kind of obvious, but it can sometimes be overlooked when we decide whether to put certain code in a server or client component.

Responsive, optimized images - `getImage()` and `<img srcset sizes />`

Astro provides getImage() function that we will use to optimize images and generate <img /> tag attributes for the client. It accepts the same arguments as the <Image /> component. Note, <img /> tag supports srcset and sizes attributes for responsive images which is sufficient for our use case. This time we don't need <picture /> support for different images (art direction) and different formats.

We will prepare different image presets (sizes) in src/libs/gallery/transform.ts#L7:

Note that only thumbnail uses responsive image, and lightbox uses a fixed size image since Photoswipe lightbox doesn't support responsive image (at least without a custom component).

// src/libs/gallery/transform.ts

// common props
const defaultAstroImageOptions = {
  format: 'webp',
};

// thumbnail preset
export const thumbnailImageOptions = {
  ...IMAGE_SIZES.RESPONSIVE.GALLERY_THUMBNAIL,
};

// lightbox preset
export const lightboxImageOptions = {
  ...IMAGE_SIZES.FIXED.MDX_2XL_16_9,
};

// getImage() wrapper
export const getCustomImage = async (options: UnresolvedImageTransform): Promise<GetImageResult> =>
  getImage({
    ...defaultAstroImageOptions,
    ...options,
  });

After that we use getCustomImage() to optimize gallery images that we previously loaded with import.meta.glob() in src/libs/gallery/images.ts#L50:

// src/libs/gallery/images.ts

export const getGalleryImages = async (): Promise<GalleryImage[]> => {
  const thumbnails = await getCustomImages(thumbnailImageOptions);
  const lightBoxes = await getCustomImages(lightboxImageOptions);

  const galleryImages = mergeArrays(thumbnails, lightBoxes).map(([thumbnail, lightbox]) => ({
    thumbnail: imageResultToImageAttributes(thumbnail),
    lightbox: imageResultToImageAttributes(lightbox),
  }));

  return galleryImages;
};

// select only needed attributes for the <img /> tag
export const imageResultToImageAttributes = (imageResult: GetImageResult): ImgTagAttributes => ({
  src: imageResult.src,
  srcSet: imageResult.srcSet?.attribute,
  ...imageResult.attributes,
});

Now we have the ready <img /> attributes (props) available to pass into the React gallery client component.

Interesting part is configuring <img /> sizes (sizes and widths args in getImage()) attribute for responsive images in src/constants/image.ts#L86:

// src/constants/image.ts

GALLERY_THUMBNAIL: {
  widths: [TW_SCREENS.XS, TW_SCREENS.SM],
  sizes: `(max-width: ${TW_SCREENS.SM}px) ${TW_SCREENS.SM}px, ${TW_SCREENS.XS}px`,
},

// actual <img /> tag attributes that are generated with the GALLERY_THUMBNAIL
<img
  sizes="(max-width: 640px) 640px, 475px"
  srcset="
    /_astro/river16.CcFOUvED_Z2d5kbP.webp 475w,
    /_astro/river16.CcFOUvED_Z16pb6L.webp 640w
  "
  src="/_astro/river16.CcFOUvED_Z1Dswo2.webp"
  width="4000"
  height="2252"
/>

// src/components/react/Gallery.tsx

<div
  id={GALLERY_ID}
  className="pswp-gallery grid grid-cols-1 gap-1 sm:grid-cols-2 lg:grid-cols-3"
>
...
</div>

If you are not familiar with defining responsive images, it's not that complicated as it seems. The code above basically says, bellow SM screen breakpoint (640px) use SM size (width) (640px) image, and if screen is wider than SM use smaller XS (475px) image. Maybe unexpected to use smaller image for larger screen, but it makes sense when you look at responsive grid that is used for the gallery layout.

You can see in grid classes that bellow sm: breakpoint image uses full width of the layout and above sm: there are 2 images per row, above lg: 3 images per row, so it makes sense to use the larger image on smaller screens.

While configuring responsive images it's advisable to preview what is generated in the browser and ensure that result meets the expectation, we have sharp images at all resolutions and not too large image files.

Blur preloader, CSS transition

Large lightbox image will handle Photoswipe on its own, we won't interfere with it for now. But we can have some nice effect on thumbnail images on infinite scroll. They are already small enough to load fast so no need to use smaller resolution image for blur preloader, we can achieve the same effect with a simple CSS transition.

The following code does that src/components/react/Gallery.tsx#L132

// src/components/react/Gallery.tsx

const [loadedImages, setLoadedImages] = useState<GalleryImage[]>([]);

const isLoadingPageImages = useMemo(
  () => !Object.values(loadedStates).every(Boolean),
  [loadedStates, loadedImages.length]
);

useEffect(() => {
  const callback: IntersectionObserverCallback = (entries) => {
    // must wait here for images to load
    if (!isEnd && !isLoadingPageImages && entries[0].isIntersecting) {
      setPage((prevPage) => prevPage + 1);
    }
  };

  // ...

  // page dependency is important for initial load to work for all resolutions
}, [observerTarget, page, isEnd, isLoadingPageImages]);


const handleLoad = (src: string) => {
  setLoadedStates((prev) => ({ ...prev, [src]: true }));
};

{loadedImages.map((image) => (
// ...
    <img
      {...image.thumbnail}
      onLoad={() => handleLoad(image.thumbnail.src)}
      alt={loadedStates[image.thumbnail.src] ? 'Gallery image' : ''}
      className={cn(
        'w-full transition-all duration-[2s] ease-in-out',
        loadedStates[image.thumbnail.src]
          ? 'opacity-100 blur-0 grayscale-0'
          : 'opacity-75 blur-sm grayscale'
      )}
    />
))}

Note that we have a map() call here and we are storing loading states for an array of images. This is because we want to have a smooth transition for the entire new page of images, not for each image separately because they will load randomly and that's less esthetic. Important part is isLoadingPageImages variable, it is used to block loading a new page until all images from the previous page are loaded. This happens in the observer callback condition if (!isEnd && !isLoadingPageImages && entries[0].isIntersecting).

Another part is CSS transition, duration-[...] should be picked so it takes more than actual thumbnail image loading time. For the transition effect, you can play around with opacity and Tailwind's filter classes and see what looks nicest to you.

Infinite scroll

We want to implement pagination through infinite scroll like e.g. Instagram. Obviously, for this, Gallery needs to be a client component and we will use IntersectionObserver to detect the bottom of the gallery and trigger loading a new page of images. For the observer we could use ready-made hooks from utility libraries like uidotdev/usehooks or streamich/react-use but lets go with our own custom implementation this time.

The code for this is in src/components/react/Gallery.tsx#L76:

// src/components/react/Gallery.tsx

// sets only page
useEffect(() => {
  const callback: IntersectionObserverCallback = (entries) => {
    // must wait here for images to load
    if (!isEnd && !isLoadingPageImages && entries[0].isIntersecting) {
      setPage((prevPage) => prevPage + 1);
    }
  };
  const debouncedCallback = debounce(callback, OBSERVER_DEBOUNCE);
  const options: IntersectionObserverInit = { threshold: 1 };

  const observer = new IntersectionObserver(debouncedCallback, options);

  const observerRef = observerTarget.current;
  if (observerRef) observer.observe(observerRef);

  return () => {
    if (observerRef) observer.unobserve(observerRef);
  };
  // page dependency is important for initial load to work for all resolutions
}, [observerTarget, page, isEnd, isLoadingPageImages]);

There are 3 important parts in this code:

We need to include page state variable in the useEffect dependencies array because we want to trigger effect execution every time new page of images loads and height of gallery increases. Also note that we read page state value from the state setter callback argument setPage((prevPage) => prevPage + 1), that's why we must also list page in useEffect dependencies array.
We need to be precise about when we are loading new page of images. Note this condition if (!isEnd && !isLoadingPageImages && entries[0].isIntersecting), it practically means "load new page of images whenever 1. we haven't loaded all images AND 2. previous page of images is fully loaded - for esthetics AND 3. the gallery is scrolled to the bottom - main prerequisite.
The observer callback() triggers quite often, so we need to limit the frequency by debouncing. Note OBSERVER_DEBOUNCE constant value needs to be fine tuned and validated through practical trial and error.

Another important and interesting part is detecting bottom of the page and displaying loader UI:

// src/components/react/Gallery.tsx

{/* control threshold with margin-top */}
{/* must be on top so loader doesn't affect it */}
<div ref={observerTarget} className="mt-0" />

<div
  className={cn(
    // duration-500 is related to OBSERVER_DEBOUNCE: 300
    'flex items-center justify-center transition-all duration-500 ease-in-out',
    shouldShowLoader ? 'min-h-48' : 'min-h-0'
  )}
>
  {shouldShowLoader && <PiSpinnerGapBold className="size-10 sm:size-12 animate-spin mt-4" />}
</div>

This can be tricky because they are circularly dependent - detection triggers showing loader and displaying loader affects position of detection <div ref={observerTarget}/>. Another thing ot note is that detection div has zero height and is placed either above or bellow the loader. It is important to be the above loader because we are interested in the bottom of the images, not the loader that will disappear from the UI in a few milliseconds anyway.

Another important part is controlling and fine-tuning the threshold of the observed element <div ref={observerTarget}/>. We do this by adjusting the positioning with className="mt-0", controlling the observers callback execution frequency with OBSERVER_DEBOUNCE, setting the transition timing for the loader element duration-500, specifying how many images we load (number of rows in the gallery) using the pageSize constant, and how many pages of images we load initially on the first screen initialPage constant.

All of these parameters are connected together and you need to fine tune them for smooth infinite scroll experience. Also note that pageSize and initialPage constants are responsive and need to be defined for each breakpoint independently for full and ergonomic control.

You can see that in the constants file in src/constants/gallery.ts#L7

// src/constants/gallery.ts

export const GALLERY = {
  GALLERY_ID: 'my-gallery',
  // Todo: make it responsive
  /** step. */
  PAGE_SIZE: {
    XS: 1,
    SM: 2,
    LG: 3,
  },
  /** page dependency in useEffect is more important. To load first screen quickly, set to 3 pages */
  INITIAL_PAGE: {
    XS: 3,
    SM: 3,
    LG: 3,
  },
  /** fine tuned for scroll */
  OBSERVER_DEBOUNCE: 300,
} as const;

And the mapping to translate constants into usable pageSize and initialPage values are defined in utility functions in src/utils/gallery.ts#L8:

// src/utils/gallery.ts

const { PAGE_SIZE, INITIAL_PAGE } = GALLERY;

// related to gallery grid css
const breakpointToPageKey = {
  XXS: 'XS',
  XS: 'XS',
  SM: 'SM',
  MD: 'SM',
  LG: 'LG',
  XL: 'LG',
  _2XL: 'LG',
} as const;

const defaultPageKey = 'LG' as const;

export const getPageSize = (breakpoint: Breakpoint): number => {
  const key = breakpointToPageKey[breakpoint] ?? defaultPageKey;
  const pageSize = PAGE_SIZE[key];

  return pageSize;
};

export const getInitialPage = (breakpoint: Breakpoint): number => {
  const key = breakpointToPageKey[breakpoint] ?? defaultPageKey;
  const initialPage = INITIAL_PAGE[key];

  return initialPage;
};

With this, we have a smooth scrolling experience on all screen sizes:

Also pay attention how we "fetch" a new page of images to update:

// src/components/react/Gallery.tsx

const fetchImagesUpToPage = (
  images: GalleryImage[],
  pageSize: number,
  nextPage: number
): GalleryImage[] => {
  const endIndex = nextPage * pageSize;
  const isLastPage = endIndex >= images.length;

  // for fetchPageImages pagination startIndex must use loadedImages and not all images and page
  const selectedImages = images.slice(0, endIndex);

  // load all images for last page
  return !isLastPage ? sliceToModN(selectedImages, pageSize) : selectedImages;
};

// converts page to loaded images
useEffect(() => {
  const upToPageImages = fetchImagesUpToPage(images, pageSize, page);
  setLoadedImages(upToPageImages);
}, [page, images, pageSize]);

There are 2 important moments here:

Since we have a static website all image urls are already included and available on the client so we don't need to calculate the starting index and can simply use zero images.slice(0, endIndex);. Usually pagination implies a network and database calls that require both startIndex and endIndex, and if we went that path we would need to calculate startIndex by finding the last element of the loadedImages state array in the images array and pass those as arguments.
Since the pageSize constant is responsive it can change when e.g. user resizes the browser window, so we call sliceToModN(selectedImages, pageSize) for evenly loaded new row. Note that we don't call this for the last page because, eventually, we want to load all images, and the correct loadedImages array length is important for calculating the isEnd variable.

Cumulative layout shift

Layout shift is important web vitals parameter and it's more challenging to optimize here since we are dealing with a dynamic client components. In the Gallery component we handle this by setting initialPage constant to load enough images to fill the initial gallery screen.

// src/constants/gallery.ts

export const GALLERY = {
  // ...
  PAGE_SIZE: {
    XS: 1,
    SM: 2,
    LG: 3,
  },
  INITIAL_PAGE: {
    XS: 3,
    SM: 3,
    LG: 3,
  },
  // ...
} as const;

Another optimization we can do is to stretch the empty gallery container element with flex grow. For that we need to modify the Page layout and pass the required Tailwind classes via the MDX frontmatter and articleClass prop.

You can see that in src/layouts/Page.astro#L38:

// src/layouts/Page.astro
---

import Centered from '@/layouts/Centered.astro';
import { getOpenGraphImagePath } from '@/libs/api/open-graph/image-path';
import { cn } from '@/utils/styles';

export interface Content {
  // ...
  class?: string;
  /** for flex flex-grow min-height to prevent layout shift for client components */
  articleClass?: string;
}

// ...

const { title, description, class: className, articleClass } = content;

// ...

---

<Centered {metadata} class={cn(className)}>
  {/* in general must not have flex, it will disable margin collapsing in MDX */}
  <article class={cn('my-prose', articleClass)}>
    <slot />
  </article>
</Centered>

Flex class is passed from MDX frontmatter in src/pages/gallery.mdx#L7:

# src/pages/gallery.mdx

---

layout: '../layouts/Page.astro'
...
class: 'max-w-5xl'
articleClass: 'grow flex flex-col'

---

import Gallery from '../components/Gallery.astro';

# Gallery

<Gallery class="not-prose grow" />

This will reduce the shift of DOM elements size, it won't make it perfect like in fully static page but for our use case it's good enough.

Another point to make is that flex container will disable margin collapsing which is important for proper vertical spacings in MDX generated HTML. So if you do that you will need to add an additional <div> wrapper element without flex to re-enable proper margin collapsing.

Lighthouse score, old gallery:

Lighthouse score, new gallery:

Please ignore the "Accessibility" score above, since the accessibility attributes aren't yet tackled on the entire website.

Lightbox with Photoswipe

For previewing images in full screen lightbox we will use ready made library Photoswipe that looks solid, reliable and flexible. We will use a basic React example from the documentation.

This is the code src/components/react/Gallery.tsx#L98

// src/components/react/Gallery.tsx

// lightbox
useEffect(() => {
  let lightbox: PhotoSwipeLightbox | null = new PhotoSwipeLightbox({
    gallery: '#' + GALLERY_ID,
    children: 'a',
    pswpModule: () => import('photoswipe'),
  });
  lightbox.init();

  return () => {
    lightbox?.destroy();
    lightbox = null;
  };
}, []);

return (
  <>
    <div
      id={GALLERY_ID}
      className="pswp-gallery grid grid-cols-1 gap-1 sm:grid-cols-2 lg:grid-cols-3"
    >
      {loadedImages.map((image) => (
        <a
          key={`${GALLERY_ID}--${image.lightbox.src}`}
          // lightbox doesn't support responsive image
          href={image.lightbox.src}
          data-pswp-width={image.lightbox.width}
          data-pswp-height={image.lightbox.height}
          target="_blank"
          rel="noreferrer"
        >
          <img
              {...image.thumbnail}
            // ...
          />
        </a>
      ))}
    </div>
  {/* ... */}
  <>

Note that for a simplicity sake we are using a simple fixed image and Photoswipe implements scale transition on its own. By default it uses a simple link <a href={image.lightbox.src}> to load the <img src /> in the full page lightbox.

This is a tradeoff for simplicity. Loading a responsive image with srcset would require integrating a custom component which could be a topic for another article. Another possible improvement is to enable closing lightbox on backdrop click on mobile which is not the case with the default config.

Lightbox image size is defined in src/libs/gallery/transform.ts#L24

// src/libs/gallery/transform.ts

export const lightboxImageOptions = {
  ...IMAGE_SIZES.FIXED.MDX_2XL_16_9,
};

// src/constants/image.ts

export const IMAGE_SIZES = {
  FIXED: {
    // ...
    MDX_2XL_16_9: { width: TW_SCREENS._2XL, height: TW_SCREENS.HEIGHTS._2XL },
  },
  // ...
};

Completed code and demo

Demo: https://nemanjamitic.com/gallery
Github repository: https://github.com/nemanjam/nemanjam.github.io

The relevant files:

# new gallery https://github.com/nemanjam/nemanjam.github.io/tree/c1e105847d8e7b4ab4aaffad3078726c37f67528
git checkout c1e105847d8e7b4ab4aaffad3078726c37f67528

src/pages/gallery.mdx
src/components/Gallery.astro
src/components/react/Gallery.tsx
src/libs/gallery/images.ts
src/libs/gallery/transform.ts
src/utils/gallery.ts
src/constants/gallery.ts
src/constants/image.ts
src/components/react/hooks/useScrollDown.tsx
src/components/react/hooks/useWidth.tsx

# old gallery https://github.com/nemanjam/nemanjam.github.io/tree/e0165b295db2ccc72bbbb7be4bdd7eb48f7dedae
git checkout e0165b295db2ccc72bbbb7be4bdd7eb48f7dedae

Outro

That was a pretty long read, thank you for your attention and dedication. Have you implemented an Astro image gallery yourself and used a different approach? Do you have suggestions for improvements or spotted anything incorrect? Don't hesitate to leave a comment below.

References

Astro gallery example, inspiration to take Photoswipe for a lightbox component https://github.com/EmaSuriano/astro-art-portfolio
Photoswipe documentation https://photoswipe.com/getting-started
Astro documentation, tutorial how to use getImage() function https://docs.astro.build/en/recipes/build-custom-img-component/
Infinite scroll with React and IntersectionObserver tutorial https://blog.logrocket.com/react-infinite-scroll/ and Codesandbox example https://codesandbox.io/p/github/Elijah-trillionz/react-infinite-scroll/master
Images in Astro as client components, useful Reddit discussion https://www.reddit.com/r/astrojs/comments/1bia6lq/how\_to\_utilize\_image\_with\_react\_component

DEV Community: Nemanja Mitic

Runtime environment variables in Next.js - build reusable Docker images

Classification of environment variables by dimension

Next.js environment variables

The problem with build-time environment variables

The solution: run-time environment variables

Server component

Static page

Client component

alizeait/next-public-env package

Usage for baseUrl for OpenAPI client

Legitimate build-time environment variables

Build and deploy reusable Docker image

Building

Deployment

Alternative approaches

Completed code

Conclusion

References

Comparing BFS, DFS, Dijkstra, and A* algorithms on a practical maze solver example

Introduction

Problem overview

App architecture

Maze representation

Class structure

Running the app

Algorithms analysis and discussion

Unweighted graphs

BFS

DFS

Weighted graphs

Dijkstra

A*

Completed code

Conclusion

References

Load balancing multiple Rathole tunnels with Traefik HTTP and TCP routers

Introduction

Prerequisites

Architecture overview

The problem

The solution

Traefik load balancer and Rathole server

Traefik HTTP and TCP routers

Rathole server config

Traefik dashboard

Rathole client

Completed code

Conclusion

References

Expose home server with Rathole tunnel and Traefik

Introduction

Prerequisites

Architecture overview

Rathole server

Rathole client and connecting with Traefik

Exposing multiple servers

Open the firewall on the VPS

Completed code

Conclusion

References

Expose local dev server with SSH tunnel and Docker

Introduction

Why is this useful

Prerequisites

Demo video

Architecture overview

Running the SSH server in Docker

Configuring HTTPS with Traefik

Tunneling multiple services

Open the firewall on the VPS

Running the tunnel

Completed code

Conclusion

References

Build a random image component with Astro and React

Introduction

What we will be building

Component hierarchy

Responsive image

`alizeait/next-public-env` package

Usage for `baseUrl` for OpenAPI client

API route vs `import.meta.glob()`

Static generation, include image urls and `map()` on the client

Responsive, optimized images - `getImage()` and `<img srcset sizes />`