#Astro Image component on Cloudflare workers

15 messages · Page 1 of 1 (latest)

low veldtBOT Oct 3, 2025, 7:29 PM

Hi @plucky radish. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

You are correct: Cloudflare Workers do not natively support the Node.js runtime, and this affects how the Astro Image component works. By default, Astro’s image optimization uses Node.js-based libraries (like sharp), which are not compatible with the Cloudflare Workers environment.

Astro’s Image component and Cloudflare Workers:

On Cloudflare Workers, the default image service (compile mode, which uses sharp) only works for prerendered routes at build time. For pages rendered on-demand (SSR), all astro:assets features—including the Image component—are disabled because they require Node.js APIs that are not available in the Workers runtime.
If you want to use image optimization on Cloudflare Workers, you need to configure the adapter to use the cloudflare image service, which leverages Cloudflare Image Resizing instead of Node.js-based processing.

How to configure:

In your astro.config.mjs, set the image service to cloudflare:

import { defineConfig } from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    imageService: 'cloudflare'
  }),
});

This will enable image optimization using Cloudflare’s native service, which is compatible with the Workers runtime. If you do not set this, image optimization will only work for prerendered (static) pages, and not for SSR/on-demand routes on Workers Cloudflare adapter options.

Summary:

Node.js-based image optimization does not work on Cloudflare Workers for SSR.
Use the cloudflare image service for compatibility with Workers.

For more details, see the official documentation: Astro Cloudflare adapter: imageService.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@plucky radish Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Let me check the knowledge base for you again. One moment! :books:

If you have added an image service to your Astro project and are deploying to Cloudflare Workers, it’s important to ensure you are using a compatible image service. By default, Astro’s built-in image optimization (using sharp) does not work in the Cloudflare Workers environment because it relies on Node.js APIs, which are not available there.

To address this, the Astro Cloudflare adapter provides several options for the imageService setting:

cloudflare: Uses Cloudflare’s native Image Resizing service (recommended for Workers).
passthrough: Uses a no-op service, so you can still use the <Image /> component for consistent markup and CLS prevention, but no image optimization will occur.
compile: Uses Astro’s default (sharp) service, but only for prerendered routes at build time. No image optimization for SSR/on-demand routes.
custom: Uses your custom image service, but you must ensure it is compatible with the Cloudflare Workers runtime.

To use Cloudflare’s image service, configure your astro.config.mjs like this:

import { defineConfig } from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    imageService: 'cloudflare'
  }),
});

If you use a service that is not compatible, image optimization will not work for SSR/on-demand routes. In that case, you can fall back to the passthrough service to at least get the benefits of the <Image /> component’s markup (width/height, alt enforcement, etc.), but without optimization Cloudflare adapter options Default image service.

If you have added a custom image service, you must ensure it does not rely on Node.js APIs unless you have specifically enabled Node.js compatibility and your code uses the node:* import syntax. Even then, only a subset of Node.js APIs are supported, and you must follow Cloudflare’s documentation for enabling this compatibility Node.js compatibility.

If you need further help, please specify which image service you have added and any issues you are encountering.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@plucky radish Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Let me check the knowledge base for you again. One moment! :books:

If you have set imageService: 'passthrough' in your Cloudflare adapter configuration, Astro will use the passthrough (no-op) image service. This means:

The <Image /> component will not perform any image optimization or transformation.
You will still get the benefits of the <Image /> component, such as automatic width, height, and alt attributes, which help prevent Cumulative Layout Shift (CLS) and provide a consistent authoring experience.
The output image will be served as-is, without resizing, format conversion, or quality adjustment Default image service.

This is the expected behavior for passthrough mode, especially on Cloudflare Workers, which do not support Node.js-based image processing. If you are expecting image optimization (resizing, format change, etc.), you will need to use a compatible image service, such as Cloudflare’s own image resizing service (imageService: 'cloudflare'), and ensure your Cloudflare account is set up for it Cloudflare adapter options.

If you are still experiencing issues (such as errors or missing images), please provide more details about the problem you are seeing. Otherwise, if your images are displaying but not optimized, this is the correct and expected result for the passthrough service.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@plucky radish Kapa.ai is still learning and improving, please let me know how I did by reacting below.

plucky radish Oct 3, 2025, 7:46 PM

@low veldt yes but why on getting

    "19:35:18 [ERROR] Error: No such module \"path\".\n  imported from \"_astro-internal_actions.mjs\""

on lgos

low veldtBOT Oct 3, 2025, 7:46 PM

Let me check the knowledge base for you again. One moment! :books:

The error message:

Error: No such module "path".
imported from "_astro-internal_actions.mjs"

indicates that your Astro project (or one of its dependencies) is trying to import the Node.js built-in module path, which is not available in the Cloudflare Workers runtime. Cloudflare Workers do not support most Node.js APIs, including path, unless you specifically enable Node.js compatibility and use the node:* import syntax Node.js compatibility.

Why is this happening?

The passthrough image service does not require Node.js modules, but some part of your build (possibly an internal Astro action or a dependency) is still trying to import path.
This is a common issue when deploying to Cloudflare Workers, as they do not provide the Node.js runtime by default Troubleshooting Node.js runtime APIs.

How to resolve:

Check your code and dependencies for any direct or indirect imports of Node.js modules like path. Make sure you are not using any Node.js-specific APIs in your server-side code.
If you need Node.js compatibility, you must:
- Use the import ... from 'node:path' syntax (not just 'path').
- Update your astro.config.mjs to include the required modules in the Vite SSR external config.
- Enable Node.js compatibility in your Cloudflare Worker configuration as described in the Astro Cloudflare Node.js compatibility guide.

If you are not intentionally using Node.js APIs, this may be coming from a package or integration that is not compatible with Cloudflare Workers. In that case, you may need to find an alternative package or integration that does not rely on Node.js built-ins.

Summary:
This error occurs because Cloudflare Workers do not support the Node.js `path` module. Review your code and dependencies for Node.js imports, and follow the compatibility instructions if you must use them. Otherwise, remove or replace any code that requires Node.js built-ins Node.js compatibility Troubleshooting.