🐛 add exports in package.json

[RoySung]

i have some issue that using vitest.
It always import cjs version for styled-components, i want to import esm version.

add exports into package.json that can help it 🙏

[quantizor]

I think more is needed... "types" is at the top and then usually "./package.json" is by itself outside of the "." block.

[RoySung]

@probablyup can you give more specific info?

[quantizor]

I just don't see why it's needed... why isn't the module package.json field being respected? It's a common bundler pattern.

[RoySung]

it's a sample project that has error when running test with vitest.
if i change version to 6.0.0-beta.12, it is working.
the version that has exports.

https://github.com/RoySung/vite-preact-playground

[Perni1984]

@probablyup I cannot 100% explain why module is not respected, but at least in the node.js world it was "just" a proposal (@see https://stackoverflow.com/questions/42708484/what-is-the-module-package-json-field-for). Node.js settled for the package.json exports field starting with node v16 and thus it's important to have proper export maps defined when you want to e.g. use styled components together with Next.js and SSR.

@probablyup would you accept a backport to 5.x aswell? As we currently would like to stay with our project on 5.x because of typing issues but running into a problem with the export maps aswell there.

So IMHO this affects everyone that wants to use styled-components with node.js based SSR in an ES modules environment.

To add here and quote two examples of favourite toolchains, also Webpack and Rollup are advocating using the exports field in package.json:

• Webpack: https://webpack.js.org/guides/package-exports/#providing-different-versions-depending-on-target-environment
• Rollup: Support "exports" field in package.json rollup/plugins#208 (comment)

[Perni1984]

Further digging into this it seems that the exports have been removed because of a problem with typings (#3800 (comment), hence #3961).

Actually IMHO the root cause of the issue with the types could be a "misconfigured" .tsconfig file where the "old" node module resolution (prior to v16) is used and not the current one. -> microsoft/TypeScript#51862 (comment)
https://www.typescriptlang.org/tsconfig#node16nodenext-nightly-builds

This "new" resolution algorithm is available since Typescript 4.7. Maybe @DavidReinberger could jump in to confirm that using the new resolution algorithm solves his problem with the types.

[quantizor]

Further digging into this it seems that the exports have been removed because of a problem with typings (#3800 (comment), hence #3961).

Actually IMHO the root cause of the issue with the types could be a "misconfigured" .tsconfig file where the "old" node module resolution (prior to v16) is used and not the current one. -> microsoft/TypeScript#51862 (comment) https://www.typescriptlang.org/tsconfig#node16nodenext-nightly-builds

This "new" resolution algorithm is available since Typescript 4.7. Maybe @DavidReinberger could jump in to confirm that using the new resolution algorithm solves his problem with the types.

Honestly I feel very uncomfortable with the exports object... it seems to be very easy to screw up and it's like impossible to test the plurality of project configs out there to make this safe to add :/

[Perni1984]

FYI I have done some extensive research on this topic during this week which I would like to summarize here.

Main assumptions

• styled components want to support CommonJs and ES modules as a dual package
• styled components targets >= node16

Node.js and module field

I can confirm that the module field is deliberately not supported by node.js (@see https://nodejs.medium.com/announcing-a-new-experimental-modules-1be8d2d6c2ff)

"While we are aware that the community has embraced the “module” field, it is unlikely that Node.js will adopt that field as many of the packages published using “module” include ES module JavaScript that may not evaluate in Node.js (because extensions are left off of filenames, or the code includes require statements, etc.)"

The module field in package.json was a proposal brought up by bundlers (for more context: originally from Rollup in 2017 - before there was a proposal for a jsnext:main field in 2015 which was superseded by the module field). So in the "bundler-world" the module field just works fine, but already the related github discussions for module and jsnext:main fields point out that there are some concerns regarding the ambiguity/flexibility of module and jsnext:main fields for different environments.

Instead Node choose to go forward with the exports field in package.json from >= v.16.x to provide

a modern alternative to "main" allowing multiple entry points to be defined, conditional entry resolution support between environments, and preventing any other entry points besides those defined in "exports". This encapsulation allows module authors to clearly define the public interface for their package.

For dual packages (CJS/ESM) like styled-components the exports field is the only way to support ES modules in a node.js environment (@see https://nodejs.org/docs/latest-v16.x/api/packages.html#writing-dual-packages-while-avoiding-or-minimizing-hazards - both approaches use the exports field).

Bundlers and the exports field

As stated above all the popular bundlers (while also supporting the module field) also are advocating for the exports field for supporting different environments:

• Webpack: https://webpack.js.org/guides/package-exports/#providing-different-versions-depending-on-target-environment
• Rollup: Support "exports" field in package.json rollup/plugins#208 (comment)
• Vite: uses Rollup under the hood for production bundling and esbuild for development and also advocates use of exports field
  • for rollup: Support "exports" field in package.json rollup/plugins#208 (comment)
  • for esbuild: https://esbuild.github.io/api/#conditions
• Parcel: exports is supported since v.2.9.0
• SWC: bundling is a feature still under construction (https://swc.rs/docs/configuration/bundling) - although as seeing in Support package.exports in NodeModulesResolver swc-project/swc#6092 exports is not supported, but fallback to module is.

Typescript and exports field

Typescript historically had two module resolution algorithms called classic and node, whereas node was renamed to node10 half a year ago (microsoft/TypeScript#51901). As styled components is stating node16 as it's minimum requirement according to the Typescript Maintainers the moduleResolution field in .tsconfig should also switch to node16 consequently, which enables the exports field for types aswell. Moreover a detailed example of how to structure the package.json with exports field in a "most compatible" way is outlined in the typescript handbook:

{
    "name": "my-package",
    "type": "module",
    "exports": {
        ".": {
            // Entry-point for `import "my-package"` in ESM
            "import": {
                // Where TypeScript will look.
                "types": "./types/esm/index.d.ts",
                // Where Node.js will look.
                "default": "./esm/index.js"
            },
            // Entry-point for `require("my-package")` in CJS
            "require": {
                // Where TypeScript will look.
                "types": "./types/commonjs/index.d.cts",
                // Where Node.js will look.
                "default": "./commonjs/index.cjs"
            },
        }
    },
    // Fall-back for older versions of TypeScript
    "types": "./types/index.d.ts",
    // CJS fall-back for older versions of Node.js
    "main": "./commonjs/index.cjs"
}

What is still unclear to me whether you need to set the type field to module in typescript to get exports field support. If so probably more needs to be changed, "type": "module" means .js files will be interpreted as ES Modules and the file ending .cjs needs to be used consequently.

Moreover this PR only adds one entry for types whereas Typescript maintainers recommend to have separate type declaration files for ESM and CommonJS even if they look the same.

Conclusion

In conclusion to have the broadest and most future proof support having an exports field in package.json is vital for styled components, and I don't see any way around it, if you want to support ES modules.

As I would assume styled components wants to support ES modules and CommonJS in a hybrid approach, @probablyup how can we support you in going forward?

[quantizor]

As I would assume styled components wants to support ES modules and CommonJS in a hybrid approach, @probablyup how can we support you in going forward?

Thank you very much for this, will review these materials today

[quantizor]

To complicate things, I think there needs to be separate entries in "exports" for the styled-components/macro and styled-components/native entrypoints. I'm preparing a commit to add those to this PR. We'll need to ship this on the test tag and probably tweak it before releasing it to the masses.

[quantizor]

I've published the code on this branch at styled-components@test for verification

[Andarist]

Those two share the same directory, they are meant to represent two different module formats (CJS vs ESM) and yet they are using the same extension (.js). This isn't correct and will cause problems one way or another. At the very least you need to either put those in different directories with appropriate package.json scopes or use different extensions for those files (with the current content of the package.json file you should use .mjs for your ESM modules)

[Andarist]

Using types like this when you are shipping dual packages isn't exactly correct and validators like arethetypeswrong will (rightfully) complain about this. If your runtime is dual, your types should be dual as well.

[quantizor]

Yeah, I couldn't figure out how to emit mts/cts using rollup. Will need to dig into tsup's source and see how they did it

[Andarist]

You are attempting to ship so-called dual package here, thus you are making yourself vulnerable to the dual package hazard. Since styled-components rely on React context, I think that you should try to avoid it as much as possible. Using .mjs wrappers strategy would be a much better choice that would be safer for the users.

[Perni1984]

@Andarist I find this very interesting - do you know of any blogpost / resource where the .mjs wrappers strategy is explained it detail, also in regards to Typescript?

[Andarist]

It's primarily described in node.js docs here but you can also find references to it in webpack and esbuild docs. We use this strategy in Emotion.

[Perni1984]

ok, thanks. I read that, but got confused with regards to Typescript and the issues described above. I'll have a look on how Emotion handles this as reference for my own lib, thanks!

[Andarist]

This order isn't exactly incorrect but I think it makes sense to think of node as the default and use browser as an override. Either way, you probably want to also include the worker condition here that will point to the non-browser code to accommodate Next.js and some other tools when they bundle for the edge workers target.