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

[remcohaszing]

Ember is in the same situation as React. .gts / .gjs gets compiled to .js, in a similar way that .tsx / .jsx gets compiled to .js. The main difference is that Ember formats are the first real life example of this happening to a content-mapped file, whereas JSX has been supported by TypeScript out of the box for a long time.

MDX is technically in the same situation too: It’s syntactic sugar over JSX that gets compiled to plain JavaScript. So if you would publish MDX, it makes most sense to compile it to .js, and accompany it with a .d.ts file.

Meanwhile MDX is also in a different situation: It’s used for documentation. I can’t think of a reason to publish it to npm, original nor transformed. Typical use cases involve a bundler or Node.js loader, where the user should use "module": "preserve" or "allowImportingTsExtensions": true. In this case this issue doesn’t affect the user.

I imagine a content mapper can specify this behaviour:

// package.json
{
  "typescript": {
    "contentMapper": {
      "exec": [/* … */],
      "compilerOptions": [/* … */],
      "dynamicConfig": /* … */,
      // Rewrite `import './example.gts` to `./example.js`
      "rewriteRelativeImportExtensions": true
    }
  }
}

And possibly a user should be able to override this.

// tsconfig.json
{
  "contentMappers": [
    {
      "package": ["ember-content-mapper"],
      "extensions": [".gjs", ".gts"],
      // Don’t rewrite `import './example.gts` to `./example.js` in this project.
      "rewriteRelativeImportExtensions": false
    }
  ]
}

This allows TypeScript to statically determine whether imports need to be rewritten. Alternatively this could be part of the openProject response.