Solving Image Path Issues in Subdirectory Deployments with Next.js + App Router + TypeScript

柳沢英俊 — Sat, 29 Mar 2025 08:43:10 +0000

When deploying a Next.js project under a subdirectory—such as /blog-sample in a production environment—handling image paths requires a bit of care.

By default, the next/image component loads images relative to the root (/) path. This causes issues when running under a subdirectory, as the paths become misaligned and images may not load correctly.

In this post, I’ll share the solution I implemented to address this issue.

Problem: Adjusting Image Paths in a Subdirectory Environment

During development, the app usually runs at the root (/), so there's no problem. However, in production—when deployed under a subdirectory like /blog-sample—image paths passed to the next/image component no longer point to the correct location.

For example, specifying src="/images/sample.jpg" would attempt to load from /images/sample.jpg, which won’t work in production where it should be /blog-sample/images/sample.jpg.

Manually adjusting paths or using conditional logic based on the environment isn’t ideal. Instead, I created a custom wrapper around next/image that dynamically handles this using environment variables, allowing consistent behavior across both development and production.

Solution: Custom Image Component

Here’s the custom wrapper I created for the next/image component:

import NextImage, { ImageProps } from 'next/image';

const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';

export const Image: React.FC<ImageProps> = ({ src, ...rest }) => {
  const normalizedSrc =
    typeof src === 'string' && src.startsWith('/') ? src.slice(1) : src;

  return <NextImage src={`${basePath}/${normalizedSrc}`} {...rest} />;
};

Key Points:

Environment Variable: Define NEXT_PUBLIC_BASE_PATH in your environment. In production, set this to the subdirectory path (e.g., /blog-sample). In development, it defaults to an empty string.
Path Normalization: If src is a string starting with a slash (/), remove the slash before combining it with the base path. This ensures src="/images/sample.jpg" becomes /blog-sample/images/sample.jpg in production, and /images/sample.jpg in development.
Flexibility: If src is not a string (e.g., StaticImageData), it’s passed through as-is, so the component won’t break.

Build Configuration

For production builds, I added the following script to package.json to define the environment variable:

"build:prod": "NEXT_PUBLIC_BASE_PATH=/blog-sample next build"

This ensures that the NEXT_PUBLIC_BASE_PATH is set properly during the build process, and the generated HTML and asset paths reflect the correct base path. In development, no additional configuration is needed.

Usage Example

Here’s how to use the custom Image component:

import { Image } from '@/components/Image';

export default function Home() {
  return (
    <div>
      <Image src="/images/sample.jpg" alt="Sample Image" width={500} height={300} />
    </div>
  );
}

This works seamlessly in both development and production, without the need for any conditional logic.

Summary

When deploying a Next.js app under a subdirectory, handling image paths can be a subtle but frustrating issue. However, combining environment variables with a custom wrapper component provides a clean and maintainable solution.

This approach is flexible enough to reuse in other projects, and if the subdirectory changes, you only need to update the environment variable at build time—no code changes required.

If you're facing a similar issue, give this approach a try!

Entering an Era of Direct Promise Passing from Server to Client in React

柳沢英俊 — Tue, 11 Feb 2025 06:44:24 +0000

Hello, fellow React enthusiasts! The React ecosystem never stops evolving, and the latest update brings an exciting new feature: you can now pass Promises directly from Server Components to Client Components. This means you can take advantage of data streaming and asynchronous rendering like never before!

What Does This Mean?

In a nutshell, instead of waiting on the server to await data and then passing it as props, you can now generate a Promise on the server and pass it directly to the client. The client then uses React’s new use hook to resolve that Promise. This approach opens up possibilities for avoiding render-blocking and keeping your code more concise.

How It Works in Code

Server Component: `src/App.js`

On the server side, we fetch data asynchronously and generate a Promise. We then pass that Promise as a prop to a Client Component. Check out the code below:

import { Suspense } from "react";
import { fetchMessage } from "./lib.js";
import { Message } from "./Message.js";

export default function App() {
  // Asynchronously fetch data on the server, which returns a Promise
  const messagePromise = fetchMessage();

  return (
    <Suspense fallback={<p>Loading message...</p>}>
      {/* Pass the Promise directly to the Message component */}
      <Message messagePromise={messagePromise} />
    </Suspense>
  );
}

Client Component: `src/Message.js`

On the client side, we use the new use hook to resolve the Promise passed from the server and render the content:

"use client";

import { use } from "react";

export function Message({ messagePromise }) {
  // Wait for the Promise to resolve and get the message content
  const messageContent = use(messagePromise);
  return <p>Message: {messageContent}</p>;
}

Benefits of This New Approach

Seamless Data Streaming:

Creating a Promise on the server and resolving it on the client prevents the server from blocking the client’s render process. This can lead to smoother and more efficient data streaming.
Cleaner Code:

Compared to traditional data fetching—where you’d await data on the server and pass it as props—this method offers a cleaner, more straightforward pattern for managing asynchronous data between Server and Client Components.
Flexibility:

The new use hook can be used anywhere inside a React component or custom hook (including loops and conditional statements), as long as it’s invoked within a component’s body.

A Few Caveats

The use hook is only available within React components or custom hooks.
The value resolved from the Promise must be serializable. Non-serializable values (like functions) cannot be passed this way.

In Summary

With the introduction of the use API in React 19, you can now pass Promises directly from server to client, making your data fetching patterns simpler and more efficient. Whether you’re chasing better performance or just cleaner code, this feature is a game changer for modern React applications.

For more details, be sure to check out the official React documentation.

Happy coding!

Forem: 柳沢英俊