Documentation in ES6, Typescript and possibly utilising native module

[graforlock]

Expected Behavior

Documentation has modern examples utilising ES6, Typescript and possibly even in-built ES6 browser modules support.

Current Behavior

Documentation has currently an old require syntax that would be decommissioned even in Nodejs in some time.

Possible Solution

Write up a modern Javascript documentation that supports toggling between non-ES6/7 and ES6/7 and maybe built-in browser module support (this point would require actual dev work in rolling up modules for instance to ES6 syntax).

Context

Above changes would modernise developer perception of Mithril giving it a popularity kick since old ES syntax is pretty much a hinderance and an eyesore.

[StephanHoyer]

ES6 👍
ES Modules 😐
TS 👎
Switcher in the docs 🤔

I'm generally sceptical that we can pull of a dynamic documentation. I'm ok with switching to ES6, I personally find ES Modules strange and avoid using them, but it's personal preference. Typescript only if it's switchable, because copy an pasting JS into typescript is easy, the other way around not so much.

[graforlock]

TS switch only because of Mithril's support - it's advantageous.

I only suggested native ES modules as it's an opportunity - Mithril doesn't have any dependencies and it is totally doable. Also, another thing is that it doesn't require a liturgy of a bundler configuration. I know that native modules aren't precisely very well implemented in browsers.

In general I think the switch to ES6 in Documentation without necessarily going deep into a webpack et al might be fine.

[orbitbot]

I'd assume this is more of a nice-to-have, automating dynamic documentation can be a bit of a PITA though I guess it's more of a chore for a one-off rewriting. Currently though the docs are mostly static, so this isn't completely trivial to implement assuming the examples wouldn't move offsite like in https://mithril-examples.firebaseapp.com/

[graforlock]

It doesn't have to be automatically generated I guess. That could be a separate feature ticket.

Syntax would just have to align with current browser capabilities. Hence, snippets with native ES6 modules would play nicely without any build steps at all while being complete at the same time - but it's just an idea.

After all, the mithril examples start from setting up HTML with script reference to the script:

https://mithril.js.org/simple-application.html

@StephanHoyer @graforlock

Is it possible that re-writing core mithril in typescript would be advantageous to keep the typescript definitions up to date? I don't think it'd be an insurmountable amount of work either.

ES modules make sense if you look at it from an ecosystem perspective, even if its not a favorite, because of the prevalence of bundlers like webpack, rollup etc and more than likely nearly all consumers of mithril (at least an outsized majority) use one, the ES modules format allows for things like dynamic imports which can really help with loading applications in the browser - just a thought.

[dead-claudia]

@ProtonScott

Is it possible that re-writing core mithril in typescript would be advantageous to keep the typescript definitions up to date? I don't think it'd be an insurmountable amount of work either.

That would be easier said than done considering how much of Mithril's internals depend on the dynamic nature of JS.

ES modules make sense if you look at it from an ecosystem perspective, even if its not a favorite, because of the prevalence of bundlers like webpack, rollup etc and more than likely nearly all consumers of mithril (at least an outsized majority) use one, the ES modules format allows for things like dynamic imports which can really help with loading applications in the browser - just a thought.

We've been considering for a while rewriting Mithril to use ES modules internally: #1886. For one, it removes quite a bit of tech debt.

@ProtonScott

Is it possible that re-writing core mithril in typescript would be advantageous to keep the typescript definitions up to date? I don't think it'd be an insurmountable amount of work either.

That would be easier said than done considering how much of Mithril's internals depend on the dynamic nature of JS.

I think it'd still be doable. If you're open to it and the communities open to it, I would be happy to take a stab at it. I think the newer version of typescript are better than pre 2.6.

ES modules make sense if you look at it from an ecosystem perspective, even if its not a favorite, because of the prevalence of bundlers like webpack, rollup etc and more than likely nearly all consumers of mithril (at least an outsized majority) use one, the ES modules format allows for things like dynamic imports which can really help with loading applications in the browser - just a thought.

We've been considering for a while rewriting Mithril to use ES modules internally: #1886. For one, it removes quite a bit of tech debt.

Sounds reasonable to me. I think it'd be relatively trivial. I looked at the referenced issue, and I don't see any thing that would be a super major hurdle, I think. I don't even think you need to worry about requires for backward compatibility or anything, on the face of it (unless there is an edge case where having commonjs exports is needed. I suppose you could always do one as es6 modules and one as commonjs)

[dead-claudia]

@ProtonScott Us migrating to TypeScript would not have any user impact. And us migrating to ES internally could be done in just a patch update, if things go according to plan.

@ProtonScott Us migrating to TypeScript would not have any user impact. And us migrating to ES internally could be done in just a patch update, if things go according to plan.

Fair is fair! 👍 Just floating ideas around it. I'll leave it be 😺