Typescript Support

[shilman]

Why

We keep getting Typescript compatibility issues like #1154 #1159 . We need a standardized way to create and maintain Typescript definitions for all @storybook/* packages

What

• Create and submit definitions to https://github.com/DefinitelyTyped/DefinitelyTyped/ @joscha
• Process for keeping type definitions up-to-date

[shilman]

@joscha I took a look at @leonidaX 's typescript example

https://github.com/leonidax/storybook-ts-less-example

I got it working on my machine and successfully added a actions.d.ts to test things out, so I basically understand what's going now. It seems like every package needs to have its own .d.ts file that describes the package's public API.

Which leads me to these questions:

1. Does typescript have any tools to automatically check whether the .d.ts file is in sync with the .js implementation? If so, we should add this to our test pass, so that we can make sure that these get updated as the packages are updated. Most of our contributors are not Typescript users, so it would be easy to forget to do this.
2. When we update the .d.ts files is there an easy way to get these synchronized into DefinitelyTyped?

I'd love to get this squared away so that we can keep our Typescript users happy!

[joscha]

Does typescript have any tools to automatically check whether the .d.ts file is in sync with the .js implementation?

Unfortunately not. There are some projects that try and auto-generate TS definitions from the API of a package (see https://github.com/ConquestArrow/dtsmake and https://github.com/Microsoft/dts-gen), but I am not sure how successful that is. The second one might work, but having any everywhere is not great.

When we update the .d.ts files is there an easy way to get these synchronized into DefinitelyTyped?

I was actually going to remove them from this repo altogether. DefinitelyTped would then be the source of truth for the TS definitions of anything storybook.

[shilman]

@joscha OK, that makes sense. So is the typical flow then:

• Person A creates a library X
• Typescript user B creates a typing @types/X
• A (or whoever) updates's X API, and the typings go out of sync
• B (or whoever) discovers the problem when they upgrade X, and updates the typings?

Or is there typically some coordination done between A and B? I'm assuming for popular libraries like lodash there is some coordination, but maybe for some random library X there is not? What are best practices here?

[joscha]

1. In an ideal world the library is written in TS and we don't need to worry about it at all.
2. In a little less ideal world, the typings would be part of the library and they would be updated with every breaking change.
3. In a little less ideal world, the typings would be in DefinitelyTyped and updated after every breaking change by the project owner after release.
4. In a little less ideal world, the typings would be in DefinitelyTyped and updated by a random person that discovers that typings and package are out of sync.

1 is out of question I think, we tried 2 but it didn't seem to work (we have 2 with the random element of 4 currently :-)) . I think storybook is currently in 4, but we can aim for 3. At least then we have lots of people being able to work on the types without any load on the core maintainers.

[shilman]

@joscha thanks for the clarification and sorry for the newbie questions. Are you proposing that Storybook adopt option 3 then? And will you take point for that (at least in the short term)?

[joscha]

@shilman I think 3 would be good. It will definitely work better than the mixture out of 2 and 4 we currently have. Short term it can be me - the nice thing about DefinitelyTyped is, that usually it works out by itself over a while, as new authors join and the bot for reviewing the pull requests selects one of any users that have previously contributed on a given package.

[shilman]

@joscha That sounds perfect. When you remove the .d.ts from the repo, please tag this issue in the PR! Many thanks for driving this, I think you'll make a bunch of people very happy (including me)! 🏆

[tmeasday]

I wonder if we need to have some kind of process around changes to the API surface. It could be tricky to enforce it for all addons that are part of the main repo though.

[joscha]

@tmeasday wouldn't all API changes be at least minor or major version bumps?

[tmeasday]

You'd hope so! I'm not sure if there's a lot of religion about it right now though. Factoring in all the addons the surface area is pretty large.

[joscha]

First of a few PRs to be opened: DefinitelyTyped/DefinitelyTyped#16970 - let's see what the DefinitelyTyped owners say.

[joscha]

Knobs addon: DefinitelyTyped/DefinitelyTyped#17399

[joscha]

Links addon: DefinitelyTyped/DefinitelyTyped#17406

[joscha]

Options addon: DefinitelyTyped/DefinitelyTyped#17408

[joscha]

Notes addon: DefinitelyTyped/DefinitelyTyped#17409

[joscha]

All PRs opened - the DefinitelyTyped ones have been merged:

• Knobs addon: add package @storybook/addon-knobs DefinitelyTyped/DefinitelyTyped#17399
• Links addon: add package @storybook/addon-links DefinitelyTyped/DefinitelyTyped#17406
• Options addon: add package @storybook/addon-options DefinitelyTyped/DefinitelyTyped#17408
• Notes addon: add package @storybook/addon-notes DefinitelyTyped/DefinitelyTyped#17409

The ones removing the types in this repo are pending:

• Remove typescript typings for @storybook/addon-knobs #1339
• Remove typescript typings for @storybook/addon-links #1342
• Remove typescript typings for @storybook/addon-options #1343
• remove typings for @storybook/addon-notes #1344

TODO:

• Wait for @types/storybook__* to be released
• Merge Remove typescript typings for @storybook/addon-knobs #1339, Remove typescript typings for @storybook/addon-links #1342, Remove typescript typings for @storybook/addon-options #1343, remove typings for @storybook/addon-notes #1344
• Release new versions

[joscha]

Release will happen with 3.2

[shilman]

Thanks much @joscha ! Fingers crossed this is a big step forward for Typescript users of Storybook!

[chinchang]

Is @types/storybook/vue coming in near future?

[joscha]

@chinchang I don't think anyone is working on these types actively at the moment, but the types setup should be fairly similar to the react ones - maybe you can open a PR against definitelytyped and we can take it from there?

[chinchang]

A colleague of mine (@pntgupta) opened a pull request for the same -> DefinitelyTyped/DefinitelyTyped#23048