Clarify behavior around "types" property

[yaymukund]

Hi, I'm noticing some possibly conflicting information. The README says:

Microbundle uses the fields from your package.json to figure out where it should place each generated bundle:

"types": "dist/foo.d.ts"          // TypeScript typings

This suggests to me that if I my package.json says "types": "dist/foo.d.ts", then Microbundle will generate dist/foo.d.ts. However, I updated my config and microbundle seems to nonetheless output to dist/index.d.ts. Looking through past issues, it also appears that this is intended behavior. I have two questions:

1. Should the "types" property determine where the typings are generated?
2. If not, does the "types" field affect Microbundle's behavior? What does it do?

I'm sorry for opening yet another issue on this. I am happy to open a PR to update docs, but I don't actually know what the intended behavior is.

Thanks for maintaining this great library :)

[marvinhagemeister]

The "types" field was originally introduced by the TypeScript team. They use it to look up type definition files for the requested package. So it's nothing specific to microbundle. We mainly hook into that and parse the folder to automatically set TypeScript's delcarationDir option to the correct path. That's where the type files will be placed.

Trouble is that TypeScript doesn't allow you to name the generated typing files. It names them after the source files. So if the main entry was index.ts, the type file will always be index.d.ts.

So what we could do is to rename the file after it was emitted. That's probably more in line with the expected behaviour.

Thanks for maintaining this great library :)

Much appreciated 🙌 It's always refreshing to see positivity in Issues ❤️

[katywings]

@marvinhagemeister Your idea with the rename would be really complicated since typescripts out-types folder structure hugely depends on the imported file paths. I tried to document the steps needed for something similar like a rename here: #643 (comment)
I think we would need like a sub budget position from SpaceX or so.

But to give a slightly more visual example:

Together with the pkg scripts:

"scripts": {
    "build": "rm -r dist && npm run build:uncool && npm run build:cool",
    "build:uncool": "microbundle --no-pkg-main -i lib/some/subfolder/uncool.ts -o dist/uncool.js",
    "build:cool": "microbundle --no-pkg-main -i lib/cool.ts -o dist/cool.js"
  }

---

As you can see the build scripts for cool and uncool are basically the same. This opens the question, why is the uncool.d.ts not saved into dist/uncool.d.ts? Why is it in dist/some/subfolder?

Because uncool.ts imports stuff from a ../../ relative parent directory:

import { importantRequirement } from "../../someUncoolDependency";

export const COOLNESS = "very hot";

console.log(importantRequirement);

This can be reproduced with the project in this lil zip:
typescript-types-out.zip

---

Since the types out folder structure completely depends on the imported files, afaik it will be very very hard to find the proper path to the d.ts file of the main entry 🙈.

[marvinhagemeister]

@katywings you're right, that explanation makes sense! Looks like I didn't think it through 😅

[yaymukund]

Thank you for the detailed explanation. I never realized declaration files' folder structure depended on the import graph! That makes sense.

I've opened the tiniest of PRs to clarify the documentation around this, to maybe save future developers a bit of hunting. Feel free to close or merge as you see fit 👍