Idiomorph not published with types

[myabc]

This would be great to have in downstream projects, e.g. here: https://github.com/opf/openproject/blob/dev/frontend/src/typings/idiomorph.d.ts

[botandrose]

Hi @myabc, thanks for the suggestion. I'm not super familiar with typescript so a few questions:

1. What exactly does it mean to publish types? Is it just including a .d.ts file in the NPM package? Does it need to be referenced in package.json? Anything else?
2. If we do this, what problem or problems are we solving?
3. Are there any possible downsides to doing this that you can see?
4. Is there a way we can automate this as part of the release process?

[myabc]

Hi @botandrose, thanks for the quick reply!

1. What "publishing types" means

There are two parts to this – both needed:

• Ship the .d.ts in the npm tarball — it's in files (or just not gitignored), so it rides along in the same package. No separate registry/upload; types travel with the JS.
• Point package.json at it so TypeScript knows where to look: top-level types field + a types condition in each exports entry. TS reads those to resolve declarations for an import.

That's it. One caveat: the .d.ts has to be module-shaped (export ...) matching the entry — a global declare var won't resolve. Hence we generate from the ESM bundle, not src.

Since code speaks a thousand words, it's probably worth taking a look at #153

2. Problems solved (from a consumers perspective at least)

1. Consumers get autocomplete + type-checking out of the box.
2. Kills hand-maintained idiomorph.d.ts copies ➡️ no drift between guessed types and real API.
3. TypeScript stops treating the lib as any.

The second one is a personal pain point for me. In addition to the typings for OpenProject, I contribute to typings for Turbo, another downstream project. Typings might have helped wiith this particular drift scenario: DefinitelyTyped/DefinitelyTyped#75138

3. Downsides

• Types become public API. Breaking a type now matters for semver; people file type bugs. _that said, it seems like the Idiomorph API has remained pretty stable, so this might not be such a big issue)
• Generated-from-JSDoc can be wrong — we already caught the morph() return-type bug. Shipping wrong types is arguably worse than none.
• Loose spots remain where JSDoc is thin (e.g. callbacks typed broadly).
• Small build/repo cost: extra tsc step, more generated artefacts in the repo (e.g. dist/*.d.ts)

IMO this is probably still worth it, but we would need to treat the generated output as something to eyeball, not juyst trust blindly.

4. Automating in release

Mostly done already done — npm run dist (release step 3) now runs types, so declarations regenerate every release.

Let me know if you need any more info! thanks again!

[myabc]

@@botandrose let me know if I can answer any more questions!

[myabc]

I've put up a PR to publish the typings via DefinitelyTyped in the meantime: DefinitelyTyped/DefinitelyTyped#75209

Obviously it would still be preferential if Idiomorph could ship its own type definitions. Type definitions via DefinitelyTyped do have a tendency to drift.

[botandrose]

@myabc Hey, sorry for the delay on this. I'll do my best to take a good look this weekend.

…

On Sat, Jul 4, 2026, 20:58 Alexander Brandon Coles ***@***.***> wrote: *myabc* left a comment (bigskysoftware/idiomorph#152) <#152 (comment)> I've put up a PR to publish the typings via DefinitelyTyped in the meantime: DefinitelyTyped/DefinitelyTyped#75209 <DefinitelyTyped/DefinitelyTyped#75209> Obviously it would still be preferential if Idiomorph could ship its own type definitions. Type definitions via DefinitelyTyped do have a tendency to drift. — Reply to this email directly, view it on GitHub <#152?email_source=notifications&email_token=AAAEH36J4X3NT5XF2SR3OYL5DFOXTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGM3DGNZYGY2KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4883637864>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAEH32HATG7WBRDC3PF23T5DFOXTAVCNFSNUABFKJSXA33TNF2G64TZHM2TEOBVGE2TSOJQHNEXG43VMU5TINRYG42TONBUGYY2C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAAEH3777MUHW26MP7RWB7D5DFOXTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGM3DGNZYGY2KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/AAAEH3ZM5NINAXUDBWWCFW35DFOXTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBYGM3DGNZYGY2KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

[myabc]

@botandrose no worries! thanks for looking into this.