Document how to declare a PostCSS plugin in an ES6/TypeScript module

[nex3]

It's currently unclear how to properly declare a PostCSS module using ES6 module syntax (which TypeScript also uses idiomatically). The suggested module.exports isn't idiomatic in these systems.

[ai]

let plugin = () => { … }
plugin.postcss = true

export default postcss

Where do you think we should change docs?

[nex3]

That was the first thing I tried, but it doesn't work if you're loading it from TypeScript:

 FAIL  test/index.test.ts
  ● Test suite failed to run

    test/index.test.ts:22:25 - error TS2349: This expression is not callable.
      Type 'typeof import("/home/nweiz/goog/pkg/js/postcss-src/build/index")' has no call signatures.

    22   return await postcss([plugin(options)]).process(input, {from: undefined});
                               ~~~~~~

I also tried

const plugin: PluginCreator = (opts: Options = {}): Plugin => { … };
plugin.postcss = true;

export = plugin;

but this produced

src/index.ts:80:1 - error TS2309: An export assignment cannot be used in a module with other exported elements.                       

80 export = plugin;
   ~~~~~~~~~~~~~~~~

So far, this is the best I've been able to manage:

const plugin: PluginCreator = (opts: Options = {}): Plugin => { … };

export = plugin;

...but this doesn't include the postcss flag, which I assume is desirable.

[nex3]

It's worth noting that the export default syntax also doesn't work with postcss-cli:

$ npx postcss-cli -u ../../build/index.js < test.css

> postcss-src@1.0.0 compile
> tsc -p .

Plugin Error (../../build/index.js): TypeError: (intermediate value).default is not a function'

[nex3]

Okay, I've found an incantation that works:

// eslint-disable-next-line @typescript-eslint/no-namespace
namespace plugin {
  export interface Options { … }
}

const plugin: PluginCreator<olugin.Options> = (opts = {}) => { … };
plugin.postcss = true;

export = plugin;

It would be nice if there were an alternative way to declare these plugins that was more module-system friendly—allowing the PluginCreator to be defined as the top-level postcss field, for example.

[ai]

These problems are coming from ESM support in TS.

1. Try export const plugin = () => {} (TS has a problem with default export)
2. Another way is to be sure that TS generate true and native ESM without any hacks from TS

[nex3]

These problems are coming from ESM support in TS.

Sure, no argument there, but that's not really something we can avoid at least until native ESM is widely used everywhere.

1. Try export const plugin = () => {} (TS has a problem with default export)

This just exports a value with the name plugin, rather than setting the module object's value.

2. Another way is to be sure that TS generate true and native ESM without any hacks from TS

If I do that I'll prevent anyone but other ESM users from using my plugin.

[ai]

If I do that I'll prevent anyone but other ESM users from using my plugin.

There is no way to have dual CJS/ESM package solution which will work in 100% cases and use default export. You must move to named export.

[nex3]

I would happily use named exports—but I'm also trying to make an idiomatic PostCSS plugin 😅. That's why I'm asking for PostCSS to accept a plugin that uses named exports.

[ai]

I think it is better to use CJS for plugins rather adding named export to JSON config loading. I have no idea about good API for named export.

But you can use named export in JS format of config.

[nex3]

But, as discussed, the CJS plugin format is difficult and messy to use correctly with TypeScript.

I have no idea about good API for named export.

What about this: if a module defines a member named postcss where typeof postcss === 'function', you treat that member as a PluginCreator.

But you can use named export in JS format of config.

When I'm writing a PostCSS plugin, only having it work for users who load plugins with JS and not for users who load plugins via JSON or postcss-cli just isn't acceptable UX—it might as well be forbidden.

[ai]

What about this: if a module defines a member named postcss where typeof postcss === 'function', you treat that member as a PluginCreator.

import a from "module"

a will not be an object with all module named exports. You need load a module in a special manner.

Also the same { postcss } export will make it more ugly for JS based configs.

import { postcss as postcssNested } from 'postcss-nested`

I rather prefer to wait a little when TS will fix ESM support (will avoid dirty hacks).

[nex3]

Are you sure TypeScript is ever going to fix this? Do they even think of this as a bug? My understanding from reading through documentation around this is that ESM's export default is explicitly and intentionally not one-to-one compatible with CJS's export =. What if you're painting the PostCSS API into a corner where it'll never work well with ESM?

[ai]

I am dreaming about the future when TS of exports default return ESM code with exports default without a hacky wrapper.

[nex3]

That's not some far-off future; I can do that today by setting "module": "es6" in my tsconfig.json. But it's not practical to do so because ES6 modules can't be consumed by CJS projects.

The issue here isn't that TypeScript decided to do something weird and idiosyncratic with ES6 syntax; the issue is that the incompatibility between CJS and native-ES6 forces users to transpile until there's a critical mass of ES6 authors out there that it's viable to ship packages that only work for them.

The good news is that you can make that world a little bit closer by making it easier to use transpiled-ES6 with PostCSS. If you don't want to support a top-level postcss function, you could instead check for module.__esModule and, if that's set, use module.default—which is what the ES6-to-CJS polyfill sets for export default.

[ai]

If you don't want to support a top-level postcss function, you could instead check for module.__esModule and, if that's set, use module.default—which is what the ES6-to-CJS polyfill sets for export default.

Hm. Cool idea.

I will look how to implement it.

[ai]

@nex3 Can you test this fix? #1773

[romainmenke]

I am no expert on ESM or CJS but have been following this thread and the pull request because I want to handle this correctly for all plugins we author from https://github.com/csstools/postcss-plugins

For some time we have been using conditional exports and rollup.
We author the plugins as ESM but everything is fed through rollup : https://github.com/csstools/postcss-plugins/blob/main/rollup/presets/package-typescript.js#L12-L13

We also have some tests for these :

• https://github.com/csstools/postcss-plugins/blob/main/plugins/postcss-base-plugin/test/_import.mjs
• https://github.com/csstools/postcss-plugins/blob/main/plugins/postcss-base-plugin/test/_require.cjs

We don't currently have tests for Typescript, but I've manually verified this and seems to work. Same for passing plugin options.

Afaik these are true:

• users can use esm to import and run PostCSS + plugins we create.
• users can use typescript to import and run PostCSS + plugins we create.
• users can use commonjs to require and run PostCSS + plugins we create.

Are we affected by this issue but not aware?
Or are we doing something different?

As stated above I am no expert, so the steps I take to verify that it works are limited by my knowledge of ESM and CJS.

[nex3]

@romainmenke It looks like the CJS blob you're distributing is set up not to cause CJS users problems. That does raise the question, though: why even bother distributing ESM, when ESM users could just as easily import your CJS blob?

[romainmenke]

That was from before my time as a maintainer of these plugins so I would have to start digging through old commits.

Most likely this happened :

• someone had an issue with some plugin in esm, deno, webpack, ...
• conditional exports were setup with the dual distibution of esm and cjs
• someone fixed the actual issue by changing/adding the rollup config

I don't dare removing it now :)

[elchininet]

Hi @nex3,

I have just read the thread, and maybe you already solved your issue since then but perhaps I can apport my two cents here. I would not recommend a named export, there are many tools/frameworks in which you need to specify the postcss plugins as strings and they are imported behind the scenes, that will not work if the plugin is exported as a named export. I was exporting postcss-rtlcss as a named export before and I changed it just to support frameworks like NextJS.

If you are still dealing with that, try a setup similar to the one that I created in postcss-rtlcss, maybe it works in your use case.

Regards

[IanVS]

Soooo, does anyone know of any docs / blogs about how to author idiomatic postcss plugins using TypeScript? I haven't come across anything from my searches so far, does everyone just write their plugins in CJS JavaScript?

[romainmenke]

You can check out how we do it here : https://github.com/csstools/postcss-plugins

summary:

• write as modern TypeScript
• use rollup to generate commonjs and es modules
• generate bundled types only for es modules

Most basic plugin : https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-base-plugin

Rollup stuff : https://github.com/csstools/postcss-plugins/tree/main/rollup