You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Allow content-mappers to return declarations instead of source files #64182
I would like to be able to opt out of lint-like TypeScript errors for content-mappers. For example, I might want to use ESM syntax in a CJS context, even if verbatimModuleSyntax is allowed. Or I would like to use export =, even is module is set to esnext.
A context where these rules don’t apply, are declaration files.
📃 Motivating Example
Content mapper authors can now return a .d.ts, .d.cts, or .d.mts extension as part of the transform response.
💻 Use Cases
I realized you can sort of categorize content mappers into two categories.
The first category is files with embedded JavaScript/TypeScript content. This includes Astro, Ember, MDX, Svelte, and Vue. This is the typical use case for content mappers. In this case it makes sense for the format to be opiniated about the module format.
The second category is static data that can be imported, but has a known shape. I just published css-modules-content-mapper. This always exports a value whose type matches Record<string, string>, but the keys are known. Other formats in this category are JSON5, TOML, YAML, XML, etc. These formats can always be written using type declarations only.
For this second category, I would really like to not care about the module format used. I want to use export = and tell TypeScript to treat it as a .d.${ext}.cts file.
A workaround is to add an @ts-ignore comment to the export = line, but that seems less ideal.
Reacted by Andrii Dieiev, Andrei Karushev, David Kaminski, Alistair Smith and Brody McKee
I just noticed TypeScript does allow CJS syntax in .cts files if module is set to esnext. But it doesn’t allow it in content-mapped file which specify the .cts extension in the transform result. This makes it a content-mapper bug, not a missing feature. I’m guessing .cts is treated as .ts.
The module format bug was fixed in #65432, but it doesn't let you do whatever you want with module format, because that would violate the law of declaration file substitutability. If you claim to be a .cts file in a Transform response, but you emit a declaration file of Component.d.mdx.ts or Component.d.ts (via an outputExtensions mapping) and you're in a "type": "module" context, then the program interprets your file as CJS while compiling, but emits an ESM declaration file. So, whatever file extension you claim to be has to agree with the module format that will be assigned to your declaration file output. (This rule applies even if you don't have declaration emit turned on, because I believe TypeScript shouldn't let you get into a situation where you have to fundamentally restructure your app to enable declaration emit, since it's a prerequisite of composite and incremental.)
It's possible to let you return declarations from Transform, but there are a few problems that would have to be solved, and it seems like the bug fix plus the module format agreement restriction removes most of the motivation for this feature request.
I’m a bit confused now. I thought claiming to be .cts, would cause TypeScript to emit Component.d.mdx.cts (unless outputExtensions is involved). MDX is not a real example, but styles.d.css.cts is.
It's possible to let you return declarations from Transform, but there are a few problems that would have to be solved, and it seems like the bug fix plus the module format agreement restriction removes most of the motivation for this feature request.
Never mind about this. I jumped to conclusions too early when I suggested this.
styles.d.css.cts isn't a recognized extension format. I proposed doing exactly that at an earlier point while investigating this issue, but it causes problems for project references and incremental compilation to not know the declaration filename of styles.css without spawning the mapper. It also makes module resolution messy to have a one-to-many mapping of source-to-declaration extensions.
Hmm ok, so then MappedOutput['extension'] essentially can’t be .mjs, .cjs, .mts, or .cts, unless the outputExtensions is used, right? (With the exception of supplemental.) If this is the case, I’ll look into changing css-modules-content-mapper to emit ESM content instead of CJS.
It can be .mts or .mjs if you're in "type": "module", and vice versa. You just need detected format agreement on the inputs and outputs; whether the format decision comes from the extension or package.json doesn't matter.
The user specifies which extensions are supported via extensions.
Map extensions to output extension in outputExtensions. This requires the user to specify rewriteRelativeImportExtensions.
The content mapper can specify the following in package.json:
Map extensions to output extension in outputExtensions, even if the content mapper can’t know the extensions that are specified by the user. This requires the user to specify rewriteRelativeImportExtensions.
In the transform RPC:
The result content must use CJS syntax if the user enabled verbatimModuleSyntax and TypeScript interprets the file as CJS.
The result content may not use CJS syntax if TypeScript interprets the file as ESM.
The content mapper has no way of knowing what response type TypeScript expects. TypeScript negotiates this based on compiler options, file name, and package.json.
I see two additions that would help with this problem:
Hide TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax' from virtual code produced by content mappers. So css-modules-content-mapper can write export default styles even if the file is CJS and the project uses verbatimModuleSyntax. It looks like this is already happening for unused locals and parameters.
Pass an array of allowed extensions in the transform params.
Activity
remcohaszing commentedon Sep 7, 2026
I just noticed TypeScript does allow CJS syntax in
.ctsfiles ifmoduleis set toesnext. But it doesn’t allow it in content-mapped file which specify the.ctsextension in the transform result. This makes it a content-mapper bug, not a missing feature. I’m guessing.ctsis treated as.ts.For a reproduction, see https://github.com/remcohaszing/css-modules-content-mapper/tree/main/fixtures/example, and change the
moduleoption toesnext.cc Andrew Branch (@andrewbranch)
andrewbranch commentedon Nov 12, 2026
The module format bug was fixed in #65432, but it doesn't let you do whatever you want with module format, because that would violate the law of declaration file substitutability. If you claim to be a
.ctsfile in a Transform response, but you emit a declaration file ofComponent.d.mdx.tsorComponent.d.ts(via anoutputExtensionsmapping) and you're in a"type": "module"context, then the program interprets your file as CJS while compiling, but emits an ESM declaration file. So, whatever file extension you claim to be has to agree with the module format that will be assigned to your declaration file output. (This rule applies even if you don't have declaration emit turned on, because I believe TypeScript shouldn't let you get into a situation where you have to fundamentally restructure your app to enable declaration emit, since it's a prerequisite ofcompositeandincremental.)It's possible to let you return declarations from Transform, but there are a few problems that would have to be solved, and it seems like the bug fix plus the module format agreement restriction removes most of the motivation for this feature request.
remcohaszing commentedon Nov 12, 2026
I’m a bit confused now. I thought claiming to be
.cts, would cause TypeScript to emitComponent.d.mdx.cts(unlessoutputExtensionsis involved). MDX is not a real example, butstyles.d.css.ctsis.Never mind about this. I jumped to conclusions too early when I suggested this.
andrewbranch commentedon Nov 12, 2026
styles.d.css.ctsisn't a recognized extension format. I proposed doing exactly that at an earlier point while investigating this issue, but it causes problems for project references and incremental compilation to not know the declaration filename ofstyles.csswithout spawning the mapper. It also makes module resolution messy to have a one-to-many mapping of source-to-declaration extensions.remcohaszing commentedon Nov 12, 2026
Hmm ok, so then
MappedOutput['extension']essentially can’t be.mjs,.cjs,.mts, or.cts, unless theoutputExtensionsis used, right? (With the exception of supplemental.) If this is the case, I’ll look into changingcss-modules-content-mapperto emit ESM content instead of CJS.andrewbranch commentedon Nov 12, 2026
It can be
.mtsor.mjsif you're in"type": "module", and vice versa. You just need detected format agreement on the inputs and outputs; whether the format decision comes from the extension or package.json doesn't matter.remcohaszing commentedon Nov 13, 2026
The user can configure the following:
extensions.outputExtensions. This requires the user to specifyrewriteRelativeImportExtensions.The content mapper can specify the following in
package.json:outputExtensions, even if the content mapper can’t know the extensions that are specified by the user. This requires the user to specifyrewriteRelativeImportExtensions.In the transform RPC:
verbatimModuleSyntaxand TypeScript interprets the file as CJS.package.json.I see two additions that would help with this problem:
TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'from virtual code produced by content mappers. Socss-modules-content-mappercan writeexport default styleseven if the file is CJS and the project usesverbatimModuleSyntax. It looks like this is already happening for unused locals and parameters.transformparams.