Adding TypeScript and Storybooks to PouchDB core development

[mqtik]

PouchDB needs types and storybooks, for easier development, better documentation for folks that want to hop in in the development cycle, and even improve starts for new beginners.

I'm happy to start working on it, gradually, with small things first, if you're all okay with it.

[dheimoz]

hey @mqtik thanks for your suggestion. I believe we can start with types.
Any particular idea you have for documentation?

[mqtik]

Absolutely.

Storybooks are a great tool, not only for development, but also for documenting things afterwards, in an automatical manner.
The good thing, is that we don't need to actually explicitly document, since it all comes from types.

So, we define the types, and the documentation will generate on its own.

I'm not sure if taking pouchdb-core just yet, I'd start with a smaller repo as a proof of concept.

https://storybook.js.org/

It's focused on the UI, however, we don't need to actually write UI components, but rather write use-cases there, so everyone can hop in on the development and easily help out.

[dheimoz]

All right, let's see the proof of concept please.

[mqtik]

@dheimoz @daleharvey see #8310

[dheimoz]

Hey @mqtik

Thank you very much for your efforts. I am a little bit overwhelm with a project. Do you mind if I take a look this weekend?

Once again. Thanks. This kind of help is what keeps Pouchdb rolling.

[mqtik]

Of course! I completely understand, we all have jobs (:

No rush, review it when you have time.

Thanks!

[sureshvv]

Correct me if I am wrong but Storybooks (just googled it) seems to be for building/prototyping UIs quickly. How would it help pouchdb development?

[mqtik]

If you use Storybooks for only building UI, then it will be just that.

PouchDB doesn't need UI for the end user, true.
The UI will be just for us, the developers, to build different scenarios, share test/cases easily, try the main component in a lot of different ways and test that, and learn a lot faster about what the core component is doing.

If I found an error in X PouchDB plugin, for example, I can just fork it, run it, and replicate the problem with a Storybook, work on a fix easily; or share it to you so you can run it and help me out.
Then we have those stories to run tests, to assure that it doesn't get broken again.

UI it's really helpful, not only for us, but for new beginners too.

If I was a beginner in PouchDB, running Pouch with a lot of written scenarios, it would be a BIG plus.

For the end-user, PouchDB will stay as-is. This only improves greatly the development/documentation/testing experience.

[fynnlyte]

I'm not quite convinced that Storybook would improve the development/testing process - doesn't it rather add more overhead because it's yet another tool to learn when trying to contribute to PouchDB? The testing setup is already quite complex

[mqtik]

You don't really have to learn anything.

Just run npm run storybook, and see all the docs, scenarios, specs and use-cases for each function/class/component.

Couldn't think of a better way to get familiar with the project fast.

Why don't you guys try to compile this PR, see what it does, how it works, and try to add a new story.

[daleharvey]

Yeh so while storybooks seem like an interesting idea they are not particularly suited for PouchDB development. One of the big issues that needs addressed by PouchDB at the moment is the complexity of the toolchain and so its a big priority to reduce the amount of tools used, not increase them.

I think being able to share test cases is very important, I worked on https://pouchdb-bug-helper.glitch.me/ that lets people press a button to fork and customise. Happy to point to other things that help efforts like that

If you find it useful I think this a cool project and would be happy to take PR's that make sure you can maintain this eassily enough but I dont think we should be bringing the whole inside the pouch project right now

[mqtik]

Yup, sounds good Dale.

I just thought of Storybooks, not only for sharing test/cases, but to also make use of TypeScript and automatically generate documentation of the code, which I think it's very useful.
It's not for users sharing their test/cases or such; but rather let new folks really understand what's going on in the code, with everything documented; Storybooks it's not intrusive.

If you want stories, create [component].stories.tsx, if not, Storybooks it's nowhere to be found. But yeah, we could drop it if you guys want.

But we could think of options; this is not for the sake of adding things to Pouch (which really, it doesn't add anything to the bundle, since it's only dev dependency), but rather take advantage of the types to explain the code itself, primarily to generate documentation.

Like, when I was writing the pouchdb-errors on TypeScript, there's a lot of undocumented things; and I only needed to know what the function expects (if it's a string, a number, docs[], ...). I still need a bit of help with that.

Have you tried to run it, Dale?

[sureshvv]

Not sure pouchdb-errors is the place to start for this. There is hardly any logic in there. You can take a part that has some complex logic and see if adding Storybooks makes it easier to understand what is going on in that module.