Fix types and exports of the package #197

MilanKovacic · 2023-10-14T05:03:42Z

Fixes #170.
This fix employs several strategies to achieve compatibility with all resolution strategies (node10, node16 - cjs, node16 - esm, bundler).

Exports are split into import and require sections — required due package having a type "module" in package.json
Types of the main export (single-spa-react.d.ts) are copied during the build process — required by TypeScript (one file can not represent types of both CJS and ESM export, even if they are identical)
Additional types (index.d.cts) for parcel CJS format are added. This file is not identical to the index.d.ts (see the last export line).
For node10 resolution strategy, parcel folder containing package.json redirects is inserted into the build. This is required for tooling that does not support subexports. Such tools will look into the "parcel" folder when doing "import ... from 'single-spa-react/parcel", locate the package.json, read the "main"/"types" field and be able to locate the CJS export (such tooling only supports CJS format).

Here is the analysis by https://arethetypeswrong.github.io/.
NOTE:
Due to rollup not inserting a compatibility layer when transpiling, in rare instances, consumers might have to access the main export with ".default". This is caused by a mix of named, and default exports.

changeset-bot · 2023-10-14T05:03:45Z

🦋 Changeset detected

Latest commit: 4b6fabe

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
single-spa-react	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

robmosca

Tested on our code base and it seems to work well. 👍🏽

joeldenning

This is a risky change. Changing the exports field is almost always a major breaking change, due to how different versions of Node, bundlers, etc handle the exports field. What version of typescript started supporting the exports field rather than types in package.json?

NOTE:
Due to rollup not inserting a compatibility layer when transpiling, in rare instances, consumers might have to access the main export with ".default". This is caused by a mix of named, and default exports.

The above sounds like it might be a breaking change.

joeldenning · 2023-10-18T23:12:22Z

.changeset/strong-otters-brush.md

@@ -0,0 +1,5 @@
+---
+"single-spa-react": patch


Whenever the exports field changes in the package.json, it might need to be a major change because of how different bundlers and NodeJS versions handle it.

Suggested change

"single-spa-react": patch

"single-spa-react": major

This fix should handle all resolution strategies (all typescript strategies), along with all popular bundlers. Still, if someone is using an obscure tool, it might behave differently, so we could treat it as a breaking change. Problem is not only with the typescript version, but a combination of typescript "moduleResolution", and bundlers. Currently, create-single-spa uses the "node" (which is actually node10) resolution strategy. What do you think?

I have inserted a compatibility layer that fixes the issue with certain bundlers requiring access to default export with ".default". Now, all of the resolution strategies are correctly handled:

Being totally honest, I would prefer calling it a major version just in case there's a weird edge case where it changes how things work. I don't know all the edge cases, but have had lots of github issues after changing my exports fields before.

I prefer single-spa-react users face no risk when doing patch upgrades.

Changed it to Major.

joeldenning · 2023-10-18T23:15:41Z

scripts/build-types.js

@@ -0,0 +1,10 @@
+import fs from "fs";
+
+function copyFile(sourcePath, destinationPath) {


nitpick: calling fs.copyFileSync directly is simpler than extracting out a reusable copyFile function. Please remove.

Removed the script, as it is no longer needed.

types/parcel/index.d.cts

…hen using node16 (cjs) resolution strategy

joeldenning · 2023-10-19T21:32:53Z

package.json

@@ -2,7 +2,7 @@
  "name": "single-spa-react",
  "version": "5.1.4",
  "description": "Single-spa lifecycles helper for React apps",
-  "main": "lib/umd/single-spa-react.js",
+  "main": "lib/cjs/single-spa-react.cjs",


Changing the main field from UMD to CJS is a breaking change. Please update the changeset to be a major

Let's change this back - we can discuss the reasons for changing to CJS in Slack and possibly in another PR

Reverted to UMD.

joeldenning · 2023-10-19T21:33:27Z

src/single-spa-react.js

@@ -375,3 +375,15 @@ function createSingleSpaRoot(opts) {

  return SingleSpaRoot;
 }
+
+/**
+ * If module is running in a CommonJS environment, a compatibility layer for node16 resolution strategy is inserted.


Please don't add extra changes in subsequent commits

types/parcel/index.d.cts

types/single-spa-react.d.cts

joeldenning · 2023-11-07T16:29:20Z

types/parcel/index.d.cts

+  Parcel as SingleSpaParcel,
+} from "single-spa";
+
+interface ParcelCompProps<ExtraProps = {}> {


Could this be moved to a shared declarations file, and then imported into both the .d.ts and .d.cts files?

import { ParcelCompProps } from './shared.d.ts';

If you agree, we can leave this as-is for now, since these files will not be needed when we migrate to typescript.

joeldenning · 2023-11-07T16:31:23Z

parcel/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../lib/cjs/parcel.cjs",


The module format for this main field should match the format for the single-spa-react package.json (UMD)

joeldenning · 2023-11-07T16:34:10Z

src/single-spa-react.js

+ * During transpilation, Rollup correctly inserts the "exports.default", and "exports.__esModule" properties, but they are not respected by some bundlers.
+ * For more information see https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/CJSOnlyExportsDefault.md
+ */
+if (typeof module !== "undefined" && module.exports) {


Let's remove this, as discussed in the call

.changeset/strong-otters-brush.md

MilanKovacic added 4 commits October 13, 2023 13:09

fix: types in the main export

2abc5fa

fix: issue with parcel exports/types

ac710c1

fix: remove required files from gitignore

bb400e3

fix: paths in the parcel package.json stub

2a83c06

chore: add a changeset

bb1aa45

MilanKovacic requested a review from robmosca October 14, 2023 05:08

This was referenced Oct 14, 2023

Fix/types #196

Closed

package.json exports when using moduleResolution node16 #170

Closed

MilanKovacic requested a review from joeldenning October 14, 2023 16:28

thejayhaykid approved these changes Oct 16, 2023

View reviewed changes

robmosca approved these changes Oct 17, 2023

View reviewed changes

joeldenning reviewed Oct 18, 2023

View reviewed changes

MilanKovacic added 4 commits October 19, 2023 12:07

fix: issue with having to access the default export with ".default" w…

898fd7b

…hen using node16 (cjs) resolution strategy

chore: switch main export to cjs version

9500fb6

fix: export re-assignment

6bf35de

chore: remove unnecessary node16 interoperability

de3a629

joeldenning reviewed Oct 19, 2023

View reviewed changes

MilanKovacic mentioned this pull request Oct 24, 2023

Why doesn't rollup (and other tooling) insert the node16 compatibility layer during ESM->CJS transpilation? arethetypeswrong/arethetypeswrong.github.io#109

Closed

joeldenning reviewed Nov 7, 2023

View reviewed changes

.changeset/strong-otters-brush.md Outdated Show resolved Hide resolved

MilanKovacic added 3 commits January 4, 2024 09:33

docs: update changelog with more details

6a220c2

fix: remove CJS compatibility layer

055387b

fix: revert "main" fields to point to UMD bundle, instead of CJS

4b6fabe

joeldenning approved these changes Jan 4, 2024

View reviewed changes

joeldenning merged commit 1141959 into main Jan 4, 2024
2 checks passed

joeldenning deleted the fix/types-and-exports branch January 4, 2024 22:59

github-actions bot mentioned this pull request Jan 4, 2024

Version Packages #192

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix types and exports of the package #197

Fix types and exports of the package #197

MilanKovacic commented Oct 14, 2023 •

edited

Loading

changeset-bot bot commented Oct 14, 2023 •

edited

Loading

robmosca left a comment

joeldenning left a comment

joeldenning Oct 18, 2023

MilanKovacic Oct 19, 2023

joeldenning Oct 19, 2023 •

edited

Loading

MilanKovacic Jan 4, 2024

joeldenning Oct 18, 2023

MilanKovacic Oct 19, 2023

joeldenning Oct 19, 2023

joeldenning Nov 7, 2023

MilanKovacic Jan 4, 2024

joeldenning Oct 19, 2023

joeldenning Nov 7, 2023 •

edited

Loading

MilanKovacic Jan 4, 2024

joeldenning Nov 7, 2023

MilanKovacic Jan 4, 2024

joeldenning Nov 7, 2023

MilanKovacic Jan 4, 2024

		@@ -0,0 +1,10 @@
		import fs from "fs";

		function copyFile(sourcePath, destinationPath) {

Fix types and exports of the package #197

Fix types and exports of the package #197

Conversation

MilanKovacic commented Oct 14, 2023 • edited Loading

changeset-bot bot commented Oct 14, 2023 • edited Loading

🦋 Changeset detected

robmosca left a comment

Choose a reason for hiding this comment

joeldenning left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joeldenning Oct 19, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joeldenning Nov 7, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MilanKovacic commented Oct 14, 2023 •

edited

Loading

changeset-bot bot commented Oct 14, 2023 •

edited

Loading

joeldenning Oct 19, 2023 •

edited

Loading

joeldenning Nov 7, 2023 •

edited

Loading