Consider having doc examples in regular JS

[pelhage]

As a JS + React dev who does not use typescript, having the documentation examples written in regular JavaScript would be greatly appreciated!

I don't think knowing TypeScript should be a pre-requisite for using a React UI library, and doing so does not make these code examples as accessible. That is just a personal opinion of course.

I'd imagine the cognitive overhead for someone who works exclusively in TypeScript to understand how these components are implemented as they intend to with TS when viewing code examples written in plain JS would be far lower than the cognitive overhead for someone completely unfamiliar with TypeScript viewing the code examples written in TS and thinking of how they will implement them in regular JS.

I will say this- on the plus side, at least by having these docs in TS I am familiarizing myself in TS which will make me more likely to consider TS in future projects.

[llorca]

Indeed, knowing TypeScript isn't a pre-requisite to use Blueprint. Many people develop with Blueprint using straight JavaScript. I can't say for sure that we'll provide JS docs but we'll certainly consider it.

If you want to learn more about the benefits of TypeScript and why we're using it, I encourage you to check out our introductory article: https://medium.com/@palantir/scaling-product-design-with-blueprint-25492827bb4a 👍

[adidahiya]

@pelhage are you referring to the code snippets in the docs? Or the actual source code for the examples hosted on Github and linked from the docs site? While it would be relatively easy to check in the transpiled JS for all the .ts files in examples/ folders, I'm a little hesitant to do so because it'll clutter the repo.

[pelhage]

Thanks for considering and sharing the link @llorca 👍

@adidahiya Referring to the code thats in the repo's examples folder after clicking "view source on Github" from the docs. I like clicking on these because the code samples in the examples folder are more in depth and give a better view of what using the component is like, but the frustration for me was that its in TS.

Can definitely understand the hesitancy re: cluttering the repo

Just wanted to bring this for your consideration. Thanks!

[adidahiya]

An idea: we might be able to add another link next to each "view source on Github" link that launches the TypeScript playground pre-filled with the source code of the example (it's all in the URL) so that JS users can see the transpiled JS on demand. There are probably practical limitations of this, like fetching the source code for the examples and browser limitations for URL length...

[pelhage]

Thats a pretty interesting idea. Is it possible to just view ES6 React syntax, rather than the transpiled-down-to-vanilla-ES5 code?

I should have been more specific with my use of "regular JS".

Most devs are using ES6, that's why I think them being able to view docs with what's most familiar would be a plus (I'm not sure what compiled React looks like)

[adidahiya]

@pelhage that's not possible with the TS playground, but theoretically possible with the compiler. Not sure if there's an option to emit JSX without transpiling to React.createElement, but you can emit ES6.

[giladgray]

(you can do "jsx": "preserve" in tsconfig to avoid transpiling React.createElement.)

TS syntax is identical to ES6 syntax with the minor addition of type annotations, which should be pretty easy to ignore or quickly teach yourself to understand. I'm not interested in downgrading the examples to un-typed ES6 because the type-checking is incredibly useful during development.

[bubuzzz]

@giladgray this is not about whether typescript is easy to learn or not. This is about how do the library approach the developers. Forcing a vast amount of developer to read the code and then convert the example to javascript is not good, especially people like me, who are trying to investigate quickly the library and do a quick comparison. For example, antd, most of the examples, i just need to copy/paste and see the result straight away.

I worked with Typescript several project as well before and I DO know that typescript is good. However, for the purpose of making the library more popular, putting something that a lot of people have to spend even 1 minute to think and test is a BIG barrier

[adidahiya]

Well, this is open source, so if enough people share your opinion @bubuzzz, they can submit a PR to make this happen. We'd be open to an automated solution that allows us to show both TS & JS code samples without maintaining two copies of the code. However, optimizing for popularity of the library is not the goal of the dev team at the moment—sorry!

[giladgray]

closing as this is not a priority for the team and most folks seem satisfied with TS examples.