`ERR_REQUIRE_ESM` when using `@netlify/blobs` inside Netlify Background Functions (CJS entry requires ESM dependency)

[marcosvrs]

When using @netlify/blobs in a Netlify Background Function that is otherwise fully ESM, the deployed background function fails with the following runtime error:

{
  "errorType": "Error",
  "errorMessage": "require() of ES Module /var/task/node_modules/@netlify/runtime-utils/dist/main.js from /var/task/node_modules/@netlify/blobs/dist/main.cjs not supported.\nInstead change the require of main.js in /var/task/node_modules/@netlify/blobs/dist/main.cjs to a dynamic import() which is available in all CommonJS modules.",
  "code": "ERR_REQUIRE_ESM",
  "stack": [
    "Error [ERR_REQUIRE_ESM]: require() of ES Module /var/task/node_modules/@netlify/runtime-utils/dist/main.js from /var/task/node_modules/@netlify/blobs/dist/main.cjs not supported.",
    "Instead change the require of main.js in /var/task/node_modules/@netlify/blobs/dist/main.cjs to a dynamic import() which is available in all CommonJS modules.",
    "    at TracingChannel.traceSync (node:diagnostics_channel:322:14)",
    "    at Object.<anonymous> (/var/task/node_modules/@netlify/blobs/dist/main.cjs:42:28)"
  ]
}

Steps to reproduce:

1. Create a Netlify Background Function with:

   import { getStore } from '@netlify/blobs';

2. Deploy with the default esbuild bundler.
3. At runtime, Netlify loads @netlify/blobs/dist/main.cjs, which contains:

   const runtimeUtils = require('@netlify/runtime-utils/dist/main.js')

   …but @netlify/runtime-utils is ESM-only. This triggers ERR_REQUIRE_ESM.

Expected behavior:

• Background Functions importing @netlify/blobs should work out of the box when using ESM.
• The CJS build of @netlify/blobs should not require() an ESM-only dependency.

Actual behavior:

• Deploy ends up using the CJS build of @netlify/blobs, which fails because it require()s an ESM-only file from @netlify/runtime-utils.

Environment:

• Netlify Functions runtime: Node 22
• Bundler: default
• @netlify/build: 35.1.2
• @netlify/plugin-nextjs: 5.12.1
• @netlify/blobs version: 10.0.7/10.0.8
• @netlify/runtime-utils version: 2.1.0
• Next.js: 14.2.31

Workarounds tested:

• Adding:

  [functions]
  external_node_modules = ["@netlify/blobs", "@netlify/runtime-utils"]

  to netlify.toml doesn't work.

• Replacing:

  import { getStore } from '@netlify/blobs';

  with:

  const { getStore } = await import('@netlify/blobs');

  doesn't work.

Request:

• Could the CJS build of @netlify/blobs be adjusted not to require() ESM-only modules?
• Alternatively, could @netlify/blobs mark @netlify/runtime-utils as ESM-only and ensure the correct entrypoint is chosen consistently?

[serhalp]

Thanks for the great detailed report and sorry for the delay here!

I believe I've got as fix ready for this, but I'm curious to understand something... Why is your "otherwise fully ESM" Background Function loading the CJS build of @netlify/blobs? 🤔 Can you share your function and its exact filename? You can omit the actual implementation — I just want to see the shape of the file and its exports. For the record, it should look like this. See also some file extension nuances. Perhaps you've landed on an old guide that uses the legacy function syntax and results in CJS?

[serhalp]

@marcosvrs I believe this should be fixed in @netlify/blobs@10.3.2. Can you please give that a try and let me know? Thanks!

[marcosvrs]

Thanks for the great detailed report and sorry for the delay here!

I believe I've got as fix ready for this, but I'm curious to understand something... Why is your "otherwise fully ESM" Background Function loading the CJS build of @netlify/blobs? 🤔 Can you share your function and its exact filename? You can omit the actual implementation — I just want to see the shape of the file and its exports. For the record, it should look like this. See also some file extension nuances. Perhaps you've landed on an old guide that uses the legacy function syntax and results in CJS?

First of all, thanks for the fix!
I have tested and it works now!
My file is a background function to generate sitemaps: packages/frontend/netlify/functions/generate-sitemaps-background.ts
And it is simply writing the sitemaps to blob, but as it takes some time to collect all thousands of products data, I need to run that in a background function:

import { getStore } from '@netlify/blobs';
import { type Config, type Context } from '@netlify/functions';
import { sitemapGenerator } from 'helpers/sitemap';

export const config: Config = {
  method: 'GET',
  path: '/api/generate-sitemaps/:locale/:key',
};

const generateSitemaps = async (req: Request, context: Context): Promise<void> => {
  console.time('Processing generateSitemaps');

  const locale = typeof context.params.locale === 'string' ? context.params.locale : undefined;
  const key = typeof context.params.key === 'string' ? context.params.key : undefined;
  if (!locale || !key) {
    console.error('TT-ERR: Missing or invalid parameters in context.');
    console.timeEnd('Processing generateSitemaps');
    return;
  }

  if (key !== process.env.TT_API_KEY) {
    console.warn('TT-WARN: Unauthorized access attempt.');
    console.timeEnd('Processing generateSitemaps');
    return;
  }

  const store = getStore('sitemap');
  await store.set(
    `sitemap-products-${locale}`,
    await sitemapGenerator({
      locale,
    }),
  );
  console.timeEnd('Processing generateSitemaps');
};

export default generateSitemaps;

[serhalp]

@marcosvrs Awesome, happy the fix worked and thank you for those details!

One more question: do you have a "type" field set in packages/frontend/package.json?