googleapis / googleapis/google-cloud-node

ESM named import of `GrpcStatus` causes runtime error

Open
#7,405 1 comment 13 reactions 1 assignee Claimed by @MarkDuckworth View on GitHub
api: firestore library: firestore priority: p2 type: bug
Dominant language
TypeScript
Stars
3.2k
Forks
712
Avg merge
2d 3h
Merged PRs (30d)
99

Description

### Description

I'm migrating a backend service from CommonJS to ESM. It uses `firebase-admin`, which in turn depends on `@google-cloud/firestore`.

After resolving all static import issues, the application starts , but immediately crashes with this runtime error:

```bash
import { GrpcStatus, FieldValue, DocumentReference, Timestamp, GeoPoint } from '@google-cloud/firestore';
^^^^^^^^^^
SyntaxError: Named export 'GrpcStatus' not found. The requested module '@google-cloud/firestore' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from '@google-cloud/firestore';
const { GrpcStatus, FieldValue, DocumentReference, Timestamp, GeoPoint } = pkg;
```

Interestingly, *all other named exports work as expected*, except for `GrpcStatus` (and also `v1`, `v1beta1`).

---

### Investigation

Upon inspecting the published code, I noticed that:

* Most named exports (e.g., `FieldValue`, `Timestamp`) are defined via `exports.{name} = ...`
* But `GrpcStatus`, `v1`, and `v1beta1` are only defined via `Object.defineProperty(module.exports, ...)`

![Screenshot](https://github.com/user-attachments/assets/eced9ea7-f34a-4d68-9ae2-2216f7dc5ad0)

As far as I understand, when Node.js attempts to statically analyze a CommonJS module (with `__esModule`), it only picks up exports defined via `exports.{name} = ...`. So the absence of `exports.GrpcStatus = ...` prevents it from being recognized as a valid named export.

Manually adding the following line resolves the issue:

```js
exports.v1beta1 = exports.v1 = exports.GrpcStatus = void 0;
```

That makes `GrpcStatus` importable in ESM as expected.

---

### Question

The JSDoc in the source indicates `GrpcStatus` is marked as **private**, but the TypeScript type definitions expose it publicly.

So: **Is `GrpcStatus` considered a public export or not?**

If it is public, the current export mechanism is broken for ESM users.

---

### Environment

* **OS**: macOS 15.5
* **Node.js**: 22.14.0
* **npm**: 10.2.5
* **@google-cloud/firestore**: 7.11.1

---

### Steps to Reproduce

Minimal repro: [StackBlitz](https://stackblitz.com/edit/stackblitz-starters-dynyexqc?file=index.js)

1. Create a Node project (Node 20+)

2. Set `"type": "module"` in `package.json`

3. Add the following to `index.js`:

```js
import { GrpcStatus } from '@google-cloud/firestore';
console.log(GrpcStatus);
```

4. Run: `node index.js`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.