fix(core): typings path and export

[sinedied]

Typescript compiler doesn't seem to find the types unless the full path is specified.
And since the types path doesn't match the exports path, it needs to be added there as well

[ggrossetie]

It seems that we need to specify a d.cts types file (CommonJS). Since we are using export default function in index.d.ts I don't think we should specify types on require.

[sinedied]

You may be right regarding the d.cts extension, seeing microsoft/TypeScript#52363
But if you look at the answers in the same thread, I think there's still need to specify the types explicitly on the require conditional, as there's not matching patch TypeScript will not load it.

My current project is configured for ESM so I could not test the CJS part, it would be helpful to check it on a real CJS project. I'll try to build a test project for that next monday

[ggrossetie]

Thanks that would be helpful!
If it works on CJS we can proceed and merge.

[Techassi]

I'm running into the same error. Related issues might be #1711 and #1588.

[ggrossetie]

@Techassi if you could confirm that the above configuration works in a CJS project that would be great.

[Techassi]

I also don't use CJS style imports, but I can create a small test project and try it out. Providing the correct path is essential, as currently the @asciidoctor/core package is unusable when using ESM style imports.

[Techassi]

I just tested it locally. This set of options in package.json seems to work:

{
  "exports": {
    "require": {
      "default": "./dist/node/asciidoctor.cjs",
      "types": "./types/index.d.ts"
    },
    "import": {
      "default": "./dist/node/asciidoctor.js",
      "types": "./types/index.d.ts"
    }
  },
  "types": "types/index.d.ts",
}

We might want to change ./types/index.d.ts to ./types/index.d.cts in the require group of options. I didn't look into generating this file (it should be a simple copy) as the build scripts seem quite convoluted.

Side note: It might be good to drop CJS style imports (and types) altogether, as the JS ecosystem is moving to the more modern ESM style. It was quite a hassle to set up this local test project as most modern tooling defaults to ESM.

[ggrossetie]

I just tested it locally. This set of options in package.json seems to work:

OK, so even if the file index.d.ts contains ESM import and export keywords it's working on a CJS project?

We might want to change ./types/index.d.ts to ./types/index.d.cts in the require group of options. I didn't look into generating this file (it should be a simple copy) as the build scripts seem quite convoluted.

I found a rollup pluign: https://github.com/Swatinem/rollup-plugin-dts

Side note: It might be good to drop CJS style imports (and types) altogether, as the JS ecosystem is moving to the more modern ESM style. It was quite a hassle to set up this local test project as most modern tooling defaults to ESM.

We dropped CJS in the first release candidate of Asciidoctor.js but the community was vocal about keeping it. Asciidoctor.js code base is now using ESM and we are using rollup to produce CJS. We might remove CJS support in the next major release.

[ggrossetie]

Superseded by #1715 (@sinedied I cherry-picked your commit)

[Techassi]

OK, so even if the file index.d.ts contains ESM import and export keywords it's working on a CJS project?

Yes seems like it. I got the correct typing information when using CJS imports and the above export options.

I found a rollup pluign: Swatinem/rollup-plugin-dts

Oh yeah, I actually use it in one of my personal projects as well. Had great success working with it. It might require some output path adjustments tho.

We might remove CJS support in the next major release.

I would love to see that!

---

Thanks for getting this merged super quick. Will test it in the real project asap!

[sinedied]

Thanks @Techassi and @ggrossetie for picking up this and completing it 👍

[Techassi]

Do you have any plans on when this will be released @ggrossetie? Currently, I still use a local dependency as a workaround.

[ggrossetie]

I will try to push a new release before my vacation (mid January)