content-mapper generates inconsistent declaration extensions, making management of package.json#exports hard / verbose

[NullVoxPopuli]

🔎 Search Terms

• content-mapper
• extensions custom declarations

🕗 Version & Regression Information

Using:

"typescript": "7.1.0-dev.20260821.1"

⏯ Playground Link

n/a

💻 Code

Here is the repo with the code: https://github.com/NullVoxPopuli/ember-content-mapper/tree/main/examples/cli-library-v2

As you can see, we have 3 different declaration extensions

• .d.ts
• .d.gjs.ts
• .d.gts.ts

Which makes the package.json exports mapping hard, because for each file type (which can change as refactoring occurs), I'd have to specify different types globs depending on which public entrypoint maps to which file.

It seems no resolving tool (node, rollup, etc) supports arrays of globs for package.json#exports like tsconfig.json#compilerOptions.paths does

🙁 Actual behavior

Too many declaration extension types

🙂 Expected behavior

I'm compliling to JS (not with tsc), so I don't think the emitted imports, nor the declarations, should have any extension other than .d.ts (with the in-declaration imports being extensionless, ofc)

Additional information about the issue

Somewhat related, but I've battled this quite a bit using TS < 7, and have hacked around it via https://github.com/NullVoxPopuli/fix-bad-declaration-output and https://github.com/embroider-build/embroider/blob/5449eb2944cd13548794ceff97df1d86a8c5d53d/packages/addon-dev/src/rollup-declarations.ts#L127

as far as I know, this is an issue in other ecosystems, like MDX
(and any ecosystem that has a custom syntax, and compiles to JS for library publishing)

Potentially related issues:

• rewriteRelativeImportExtensions: tsc doesn't rewrite extensions in emitted declaration files #61037

Docs I know about:

• https://www.typescriptlang.org/tsconfig/#allowImportingTsExtensions
• https://www.typescriptlang.org/tsconfig/#allowArbitraryExtensions (I think ? (idk actually) this option might be the problem, because it assumes the file isn't transformed for publish)

The full expanded tsconfig

{
    "compilerOptions": {
        "allowJs": true,
        "allowImportingTsExtensions": true,
        "emitDeclarationOnly": true,
        "declaration": true,
        "declarationDir": "./declarations",
        "declarationMap": true,
        "experimentalDecorators": true,
        "module": "esnext",
        "moduleResolution": "bundler",
        "noEmit": false,
        "noUncheckedIndexedAccess": true,
        "noEmitOnError": false,
        "rootDir": "./src",
        "skipLibCheck": true,
        "strict": true,
        "target": "es2024",
        "types": [],
        "verbatimModuleSyntax": true,
        "allowSyntheticDefaultImports": true,
        "isolatedModules": true,
        "preserveConstEnums": true
    },
    "files": [
        "./src/index.ts",
        "./src/template-registry.ts",
        "./src/utils/format.ts"
    ],
    "include": [
        "./src/**/*"
    ],
    "exclude": [
        "<repo>/examples/ember-library-v2/declarations"
    ]
}

I've also tried with adding:
allowArbitraryExtensions: true and rewriteRelativeImportExtensions: true

[RyanCavanaugh]

This is intentional and necessary, because if the format was

filename.extension.d.ts

then you'd have a conflict.

Let's say you had

./App.myFx.ts <- source file
./App.myFx <- template or whatever

then they'd both map to App.myFx.d.ts, trying to overwrite each other.

[NullVoxPopuli]

that's understandable -- but that doesn't help solve the root of the problem:

how do I generate declarations for my compiled-to-JS code?

there seems to be no understanding from tsc that an external tool could be changing the extensions, and compiling away anything "custom" in to platform-compatible code

for js files, I would expect .d.ts

[andrewbranch]

How are we supposed to know that your external build tool transforms avatar.gts to avatar.js and not avatar.gts.js or avatar.gts/index.js or something completely different? The declaration file is there to make the import you wrote, import "./avatar.gts" work. If your build tool is turning avatar.gts into avatar.js, that implies it's also rewriting imports of "./avatar.gts". If it's renaming files and rewriting source imports, why would that tool not have the responsibility of doing the same thing for declaration files? You are correct that tsc has no understanding that an external tool could be changing the extensions, but how would you propose we are supposed to know that?

[NullVoxPopuli]

at the most verbose, a config can be used:

// tsconfig.json#compilerOptions
"declaration": true | false | {
  // implies ".d.ts", 
  // and all imports matching files that point at other files are stripped of their extensions, 
  // or using ".js" as the extension, as is already supported in node-ESM
  ".vue": ".js",  
  ".mdx": ".js",
  ".svelte": ".js",
  ".gjs": ".js",
  ".gts": ".ts",

  // or one flag:
  "externallyCompiledToJS": true
}

just a couple ideas

I think doing this in TS makes sense, because otherwise, everyone who isn't using js/ts (with the exception of the special treatment react gets, which bypasses all these problems), has to implement the same logic

[andrewbranch]

everyone who isn't using js/ts (with the exception of the special treatment react gets, which bypasses all these problems), has to implement the same logic

I actually think Ember is an exception here for having a 1:1 emit compilation. I think most of these other ecosystems tend to ship uncompiled .vue etc. to npm packages and then are bundled in application usage. Do you know of others who are actually in the same boat as Ember?

[NullVoxPopuli]

MDX, for sure (and they have the same problem I'm describing, iirc -- but I'll let Remco Haszing (@remcohaszing) expand on that)

I'd like for the other ecosystems to come up with an always intermediary (or better: final) just publish JS to npm format, because it means consuming application have less transpilation work to do