Add export specification #9697

tobiasdiez · 2022-05-08T09:35:43Z

Define Package entry points using the exports field in package.json. There might be additional paths that you want to expose and I'm not sure if the utilities should be exposed by this package.json file or by its own one.

Fixes #9048 and probably #9938, #9156, #8218, apollographql/apollo-feature-requests#287

Checklist:

If this PR is a new feature, please reference an issue where a consensus about the design was reached (not necessary for small changes)
Make sure all of the significant new logic is covered by tests

apollo-cla · 2022-05-08T09:35:45Z

@tobiasdiez: Thank you for submitting a pull request! Before we can merge it, you'll need to sign the Apollo Contributor License Agreement here: https://contribute.apollographql.com/

rosskevin · 2022-06-03T17:01:57Z

package.json

  "main": "./dist/main.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/main.cjs"
+    },
+    "./core": {
+      "import": "./core/index.js",
+      "require": "./core/core.cjs"
+    },
+    "./link/error": {
+      "import": "./link/error/index.js",
+      "require": "./link/error/error.cjs"
+    },
+    "./utilities/policies/pagination": {
+      "import": "./utilities/policies/pagination.js"
+    }
+  },


To be compliant, I read the typescript handbook as the following (remove commented lines, add in types, and note the wrong published module path has not dist). Also note I added in the link/core module:

// -"main": "./main.cjs", // -"module": "./index.js", // -"types": "./index.d.ts", "exports": { ".": { "types": "./index.d.ts", "import": "./index.js", "require": "./main.cjs" }, "./core": { "types": "./core/index.d.ts", "import": "./core/index.js", "require": "./core/core.cjs" }, "./link/core": { "types": "./link/core/index.d.ts", "import": "./link/core/index.js", "require": "./link/core/error.cjs" }, "./link/error": { "types": "./link/error/index.d.ts", "import": "./link/error/index.js", "require": "./link/error/error.cjs" }, "./utilities/policies/pagination": { "types": "./utilities/policies/pagination.js", "import": "./utilities/policies/pagination.js" } },

I will note however, that while I think the above exports are correct according to the handbook, that I still receive errors when attempting to use option "moduleResolution": "nodenext", but it is fine when using the more typical node resolution. (I believe this to be a bug with typescript and export * from using nodenext resolution and I'm working on a test case for them).

Thanks for the input. I believe though that the dist prefix is necessary, since that's where the files are in the distributed package. Feel free to add your other changes as github suggestions, then I will merge them.

@tobiasdiez I have confirmed that dist in not in the published package. See https://unpkg.com/@apollo/client@3.6.6/dist or

It seems like you are right and there is indeed no dist folder. But the dist path is akso in "main" and "module", strange...

These paths must be rewritten during the build process. If you yarn patch @apollo/client and open an editor, you can see the produced paths more easily.

rosskevin · 2022-06-03T21:57:19Z

Here is a reproduction of apollo failing as a pure ESM library import due to what I believe is the lack of proper exports (I could be wrong). Note that switch typescript to "moduleResolution": "node" instead of "moduleResolution": "nodenext" allows this to succeed, which supports the argument that the problem is exports based.

https://github.com/rosskevin/ts-esm-workspaces/tree/apollo-exports

Mordred · 2022-06-30T13:13:09Z

Here is my not working use case https://github.com/Mordred/apollo-client-esm

I created new project and added "type": "module" to package.json. NodeJS throws a SyntaxError that @apollo/client is CommonJS module.

It would be nice to have exports defined - but do not forget to add ./link/schema, ./link/ws and more which are not currently in this PR but are in the docs (e.g. https://www.apollographql.com/docs/react/api/link/apollo-link-schema/)

tobiasdiez · 2022-09-08T15:03:48Z

@Mordred Thanks for the suggestion. Could you provide the other exports as PR review suggestions, so I can easily commit them to this PR in your name?

@jpvajda @MrDoomBringer I would very much appreciate if you could find the time to review this PR.

jpvajda · 2022-09-08T20:37:48Z

👋 @tobiasdiez I noticed a weird Circle CI error on this PR, so I'm curious what might be occurring here. Jyst adding a few people from the team to check this out for you. @bignimbus @hwillson

Could not find a usable config.yml, you may have revoked the CircleCI OAuth app.Please sign out of CircleCI and log back in with your VCS before triggering a new pipeline.

bignimbus · 2022-09-09T13:58:41Z

Thanks for the tag @jpvajda and thanks for your contribution @tobiasdiez! I haven't been able to narrow down the issue with CircleCI - @tobiasdiez what do you see when you click the "Details" link next to "CircleCI Pipeline?"

I was able to get a build started by pushing a branch with these changes. See https://app.circleci.com/pipelines/github/apollographql/apollo-client/16912/workflows/ae50495f-993e-4359-94f8-b3b37dcd2502/jobs/93836 - it looks like there are some failing tests regarding modules:

     Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './apollo-client.cjs' is not defined by "exports" in /home/circleci/project/scripts/memory/node_modules/@apollo/client/package.json
     Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './react' is not defined by "exports" in /home/circleci/project/scripts/memory/node_modules/@apollo/client/package.json

Given @Mordred's comment, I think we need to take a closer look at our test coverage to ensure that all entry points are covered.

tobiasdiez · 2022-09-09T15:35:55Z

@bignimbus Thanks for investigating. I get a similar message on CircleCI:

Could not find a usable config.yml, you may have revoked the CircleCI OAuth app.Please sign out of CircleCI and log back in with your VCS before triggering a new pipeline.

It's also not working if I try to create a new PR: #10086. So maybe its best if you (or someone else) creates a new PR with the changes.

bignimbus · 2022-09-09T20:22:26Z

Thanks for trying again @tobiasdiez 🙏🏻 I would definitely like to figure out what might be going on. Regardless of whether it's a broader issue with our CircleCI config or something happening in your specific account, I'd like to make sure you're fully able to contribute to our community. Would it be ok for me to reach out directly via your Twitter DMs next week and try a couple of debug steps? Completely fine if you'd prefer not to, whatever works for you!

tobiasdiez · 2022-09-09T21:36:48Z

I've now created a circleci account (via github oauth) and it seems like this did the job. Strange though...

MrDoomBringer · 2022-09-12T02:29:59Z

Hey @tobiasdiez ! Thanks for the ping on this.

The question of entrypoint coverage in this thread looks to me to be a bit of a challenge. To truly prevent a breaking change, we'd need to cover (just about) every export statement in @apollo/client/..., rather than only the module entrypoints defined in config/entrypoints.js and otherwise mentioned in the docs.

That would look something like this exports definition ...

"exports": {
    "./testing": {
      "import":"./testing/index.js",
      "require":"./testing/testing.cjs"
    },
    "./testing/core": {
      "import":"./testing/core/index.js",
      "require":"./testing/core/core.cjs"
    },
      "./testing/*": "./testing/*.js",
      "./testing/*.js": "./testing/*.js"
  }

... to support the public entrypoints we currently have in @apollo/client/testing, for example:

// foo.js
// > node --experimental-specifier-resolution=node foo.js
import * as a from '@apollo/client/testing/core/mocking/mockClient'
import * as b from '@apollo/client/testing/core/mocking/mockClient.js'
import * as c from '@apollo/client/testing/core/itAsync'
import * as d from '@apollo/client/testing/core/itAsync.js'
import * as e from '@apollo/client/testing/core'
import * as f from '@apollo/client/testing/react/MockedProvider'
import * as g from '@apollo/client/testing/react/MockedProvider.js'
import * as h from '@apollo/client/testing'

Even taking advantage of node's subpath export patterns I worry how maintainable our package.json will be after covering every public entrypoint we have right now.

Also, doing all this might be avoiding what the team at nodejs.org is trying to get us to do:

allowing module authors to clearly define the public interface for their package.

It might be that the correct move here includes targeting a later release (Maybe 4.0?), then some planning on what we want our public interface to be and reorganizing our codebase to make that interface more easily accessible.

I'm not yet totally certain on my answer here, please let me know if I missed something.

All the best,
Emmanuel, Intern :-)

tobiasdiez · 2022-09-12T07:55:10Z

I guess it depends on what you define as the public interface. For example, direct imports of js files like '@apollo/client/testing/core/mocking/mockClient.js' I would consider as a private implementation detail whose public interface is '@apollo/client/testing/core/mocking/mockClient'.

But yes, in general, I agree it would be nice if apollos interface could be streamlined and many deep imports combined (e.g. @apollo/client/testing being the only entrypoint). But let's not do this as part of this PR.

rosskevin · 2022-10-27T16:59:15Z

@MrDoomBringer perhaps a breaking change is necessary. I agree that the apollo packaging is quite unconventional, but regardless, people using ESM are broken because apollo packages are not providing an updated picture of their package via the exports specification. I'm for a major bump if the dist can get cleaned up and the exports specified appropriately.

For what it is worth, here is my current yarn patch - I know that it is incomplete (indeed I already noted the lack of cjs file in the last entry)...but it is getting me by (so far).

diff --git a/package.json b/package.json
index 3a2bf8a3ead2ca597564f8fbfafa8af78c385a36..d4aee2f69d4e77e8bcf836265ce8bc2c2b10958a 100644
--- a/package.json
+++ b/package.json
@@ -16,6 +16,37 @@
   "main": "./main.cjs",
   "module": "./index.js",
   "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./main.cjs"
+    },
+    "./core": {
+      "types": "./core/index.d.ts",
+      "import": "./core/index.js",
+      "require": "./core/core.cjs"
+    },
+    "./link/core": {
+      "types": "./link/core/index.d.ts",
+      "import": "./link/core/index.js",
+      "require": "./link/core/error.cjs"
+    },
+    "./link/error": {
+      "types": "./link/error/index.d.ts",
+      "import": "./link/error/index.js",
+      "require": "./link/error/error.cjs"
+    },
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "import": "./testing/index.js",
+      "require": "./testing/testing.cjs"
+    },
+    "./utilities/policies/pagination": {
+      "types": "./utilities/policies/pagination.d.ts",
+      "import": "./utilities/policies/pagination.js"
+    }
+  },
   "sideEffects": false,
   "react-native": {
     "./dist/cache/inmemory/fixPolyfills.js": "./cache/inmemory/fixPolyfills.native.js",

revmischa · 2022-11-21T18:27:34Z

I think it makes total sense to simplify the public interface and release as 4.0.0
All of the @apollo/client code is getting bundled in both the client and server-side code of my application which makes web pages slower to load and lambda graphql resolver functions slower in cold starts. If this can help, it will be a great improvement for my users.
Ref: apollographql/apollo-feature-requests#287 (comment)

tobiasdiez · 2023-03-08T02:38:46Z

How should we proceed here? Is there something I can do to move this forward?

phryneas · 2023-03-08T09:11:09Z

@revmischa This is something we cannot do without a 4.0, and we will not do a 4.0 just for this. Reviewing the whole bundling setup is something we will be doing for the next major, especially with ESM in mind.

Unfortunately, there is still no generally-agreed way of serving ESM without breaking some build or bundling tools. For example, see over in the Redux repo, where we are trying to do this at this moment. Every change published in an alpha generates a bug report that something is broken.

At this point, it's probably best that you use something like the patch suggested in #9697 (comment) until we get ready for the next major (and someone hopefully figures this problem space out before that).

rschristian · 2023-03-18T07:52:37Z

package.json

@@ -16,6 +16,23 @@
  "main": "./dist/main.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",


Without "type": "module" set, .js is interpreted as CJS, not ESM. You need to use .mjs to refer to ESM in a CJS package (which is the default).

JasonKleban · 2023-05-04T14:56:37Z

Related #9976

phryneas · 2023-09-14T14:09:14Z

I just mentioned this over in #10620 - at the point where we get to this change (definitely in the next major release!), we will likely have to adopt tooling that will autogenerate these exports fields.

As I'm doing some housekeeping, I'm going to close this PR for now - that definitely doesn't mean that we won't do this though!
Really appreciate the PR and bringing this up 👍

Add export specification

0ab4e49

Add main entry point

1ccdfce

tobiasdiez mentioned this pull request May 8, 2022

Migrate to Nuxt 3 JabRef/JabRefOnline#1009

Merged

18 tasks

jpvajda added the 🏓 awaiting-team-response requires input from the apollo team label May 13, 2022

rosskevin suggested changes Jun 3, 2022

View reviewed changes

This was referenced Jun 3, 2022

ES module support for @apollo/client/utilities #9008

Closed

ESM only monorepo w/project references error without main fallback microsoft/TypeScript#49266

Closed

tobiasdiez mentioned this pull request Jun 24, 2022

Issues depending on external libraries JabRef/JabRefOnline#770

Open

51 tasks

Merge branch 'main' into patch-2

7b2f3c3

Merge branch 'main' into patch-2

6335636

Merge branch 'main' into patch-2

3dca41f

MrDoomBringer self-assigned this Sep 12, 2022

bignimbus removed the 🏓 awaiting-team-response requires input from the apollo team label Dec 2, 2022

bignimbus unassigned MrDoomBringer Dec 13, 2022

bignimbus mentioned this pull request Jan 3, 2023

Exports ES #10393

Closed

tobiasdiez mentioned this pull request Jan 23, 2023

Activate SSR JabRef/JabRefOnline#1725

Closed

yusufkandemir mentioned this pull request Feb 14, 2023

@apollo/client requires React to be installed when using @graphql-tools/links ardatan/graphql-tools#4901

Closed

4 tasks

rschristian reviewed Mar 18, 2023

View reviewed changes

alessbell added the 🛫 in-progress label Apr 3, 2023

phryneas mentioned this pull request May 12, 2023

Missing "exports" property in package.json #9976

Open

phryneas mentioned this pull request Jun 16, 2023

nextjs release breaks server component use of Apollo query latest release #10974

Open

jerelmiller added the 🍳 breaking change label Aug 30, 2023

phryneas closed this Sep 14, 2023

github-actions bot locked as resolved and limited conversation to collaborators Oct 15, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add export specification #9697

Add export specification #9697

tobiasdiez commented May 8, 2022 •

edited

Loading

apollo-cla commented May 8, 2022

rosskevin Jun 3, 2022 •

edited

Loading

tobiasdiez Jun 4, 2022

rosskevin Jun 7, 2022

tobiasdiez Jun 11, 2022

rosskevin Oct 27, 2022

rosskevin commented Jun 3, 2022

Mordred commented Jun 30, 2022

tobiasdiez commented Sep 8, 2022

jpvajda commented Sep 8, 2022

bignimbus commented Sep 9, 2022

tobiasdiez commented Sep 9, 2022

bignimbus commented Sep 9, 2022

tobiasdiez commented Sep 9, 2022

MrDoomBringer commented Sep 12, 2022 •

edited

Loading

tobiasdiez commented Sep 12, 2022

rosskevin commented Oct 27, 2022 •

edited

Loading

revmischa commented Nov 21, 2022 •

edited

Loading

tobiasdiez commented Mar 8, 2023

phryneas commented Mar 8, 2023 •

edited

Loading

rschristian Mar 18, 2023

JasonKleban commented May 4, 2023

phryneas commented Sep 14, 2023

Add export specification #9697

Add export specification #9697

Conversation

tobiasdiez commented May 8, 2022 • edited Loading

Checklist:

apollo-cla commented May 8, 2022

rosskevin Jun 3, 2022 • edited Loading

Choose a reason for hiding this comment

tobiasdiez Jun 4, 2022

Choose a reason for hiding this comment

rosskevin Jun 7, 2022

Choose a reason for hiding this comment

tobiasdiez Jun 11, 2022

Choose a reason for hiding this comment

rosskevin Oct 27, 2022

Choose a reason for hiding this comment

rosskevin commented Jun 3, 2022

Mordred commented Jun 30, 2022

tobiasdiez commented Sep 8, 2022

jpvajda commented Sep 8, 2022

bignimbus commented Sep 9, 2022

tobiasdiez commented Sep 9, 2022

bignimbus commented Sep 9, 2022

tobiasdiez commented Sep 9, 2022

MrDoomBringer commented Sep 12, 2022 • edited Loading

tobiasdiez commented Sep 12, 2022

rosskevin commented Oct 27, 2022 • edited Loading

revmischa commented Nov 21, 2022 • edited Loading

tobiasdiez commented Mar 8, 2023

phryneas commented Mar 8, 2023 • edited Loading

rschristian Mar 18, 2023

Choose a reason for hiding this comment

JasonKleban commented May 4, 2023

phryneas commented Sep 14, 2023

tobiasdiez commented May 8, 2022 •

edited

Loading

rosskevin Jun 3, 2022 •

edited

Loading

MrDoomBringer commented Sep 12, 2022 •

edited

Loading

rosskevin commented Oct 27, 2022 •

edited

Loading

revmischa commented Nov 21, 2022 •

edited

Loading

phryneas commented Mar 8, 2023 •

edited

Loading