near-examples
Convert frontend to typescript
Why
- developer experience: having TypeScript properly configured in a new project makes me feel immediately more productive in an unfamiliar codebase – I can type the name of a variable and get hints on the sort of stuff I can do with that variable
- code maturity: if I were making a full-size codebase, as opposed to a demo, I would want the assurances & speed that TypeScript brings. Given that we want people to use this app as a starting point, we do them a favor by starting them off with TypeScript.
- improving other tools: we will test drive the typings that our other libraries provide and make sure they are adequate
Why Not
- complexity: it's harder to see the core example through the layers of possibly-unfamiliar tech. (My response to this is that we can have other examples that are simpler.)
That's the only argument against doing this. I come out on the side of "it's worth doing."
How
This project already has eslint configured to check typescript. At least somewhat. It may be useful to reference the examples website.
@chadoh I personally highly dislike using TypeScript for apps. It degrades my development experience, not improves it. Especially for something small like guest book.
Not super sold on big projects either. NEAR Studio was using TypeScript with React and literally every time it was only getting in a way without providing any meaningful benefits.
However I agree there is utility in providing TypeScript version for people who want to use TypeScript. But that should be an option, not the only thing available.
& speed that TypeScript brings.
What do you mean? How and where TypeScript brings speed? It makes dev environment slower and AFAIK has no impact on production speed generally.
@vgrichina Do you think in backend typescript is better? I've seen quite a lot js frontend + ts backend combination recently.
@ailisp I think libraries get a little more benefit from TS, than apps because of IDE support (.d.ts files often allow for better code completion). However when using JS ES6 syntax for classes, etc – VS Code is almost as good in terms of IDE support.
TS backend with JS frontend seems like smth that would happen because backend devs often come from statically typed languages (Java, Go, C#, C++, etc).
I find TypeScript especially painful on frontend, as it slows down iteration speed even further than usual bundler tooling. However on frontend you generally want to see results of changes in live app as fast as possible (because you need to do a lot of eye-balled iterations to get well-polished UI). It's less of a pain if you don't have to eyeball results of your changes all the time.
TL;DR; I don't see any benefit of TS in this example.
I find TS mildly useful in big-ish projects where you need to define your interfaces and keep them at least some-what checked. In the single-file example, it will only make things messier. Yet, it may help to catch some typos when people start playing with the demo. On the other hand, TS will get in a way when you hack around a demo project. Sometimes, I find it painful to satisfy TS (meaning, I feel that I do a useless job, though I admit that it provides some sanity over JS).
@vgrichina Next.js tooling does live-reloading pretty quickly no matter TS or JS file I edit. I find it painful to use TS for the backend since in this case it indeed slows me down as plain JS does not need any transformation and you can start the execution immediately. I am looking forward to rewriting my heap of hacks called "Explorer backend" into Rust.
When I started learning to use https://thegraph.com/, I was so glad that they made their demo app use TypeScript. I thought that led to a great developer experience. I didn't have to look up documentation to figure out what I could do with a variable, I could just type it, followed by a . – and boom! My editor would tell me what I could do with it. It made me feel immediately productive.
I get this same speed boost with large projects. I don't have to do nearly as much searching around & reading; I can type variable names and have my editor tell me what I can do with them. (Maybe I need to play with my editor more for ES6, because I have not experienced nearly the same level of helpfulness without TypeScript.) If a well-configured linter makes a developer 3% more productive, I think TypeScript can make a developer 10% more productive. A whole bunch of bugs get caught and squashed before I even leave my editor.
As for code-loading & browser refresh rate, two thoughts:
- I haven't noticed that my code compiles more slowly when I use TypeScript
- As someone who has done primarily frontend development, I find that easily less than half of my time is spent tweaking the visual appearance of things. All the other time gains the speed boost from TypeScript that I mentioned above. And when I am visually tweaking things, I do so directly in the web inspector in my browser, rather than in my editor. Then I copy & paste to my editor. I suspect this is very common, as browsers are super helpful with this sort of visual tweaking.
Finally, even if we do decide to forego adding TS on this example, I think we should ensure that engineers who want to use TypeScript have a great experience within the NEAR ecosystem. And unfortunately, I don't think that's true right now. Since we aren't using TS much ourselves, it appears that our typings are not quite accurate in all cases. I started experimenting with adding TS to this repo, and got complaints about some of the ways this repo uses nearlib, even though it's valid. I think we ought to add TypeScript to at least some demo apps so that we can find & fix these sorts of issues.
And unfortunately, I don't think that's true right now. Since we aren't using TS much ourselves, it appears that our typings are not quite accurate in all cases. I started experimenting with adding TS to this repo, and got complaints about some of the ways this repo uses nearlib, even though it's valid.
I absolutely agree with that. I find myself reading near-api-js sources more often than I should just to make sure that it is going to do what I expect (and the docs are not helping much :disappointed:)
Well, on the second thought, I think this project won't need much TypeScript annotations itself, but it will enable IDE hints which is a big win. I changed my mind and I think it is worth converting to TypeScript (especially, if near-api-js gets fixed)
Since we aren't using TS much ourselves, it appears that our typings are not quite accurate in all cases.
hmm, aren't our typings generated from TypeScript source code in nearlib? Though TBH I really hate that VS Code is jumping to typings instead of source code in TypeScript libraries (is there any way to fix it?).
I'm all for having typescript for frontend as an option (same as we have Rust and AssemblyScript as options), but I don't think that we should be forcing TypeScript as the main way to do web frontend. It's largely a matter of taste (and so would be likely hated by some people as much as loved by other people), so need to be a choice.
Note that most of the linting benefits can be obtained by running TypeScript as linter for regular JS code. I think it would be far less controversial to enable this by default: https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html
hmm, aren't our typings generated from TypeScript source code in nearlib?
I guess the point was that our nearlib types are not accurate enough in the first place.
I'm all for having typescript for frontend as an option (same as we have Rust and AssemblyScript as options), but I don't think that we should be forcing TypeScript as the main way to do web frontend. It's largely a matter of taste (and so would be likely hated by some people as much as loved by other people), so need to be a choice.
Note that most of the linting benefits can be obtained by running TypeScript as linter for regular JS code. I think it would be far less controversial to enable this by default: https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html
These are good points. I'll try that out and see what I think, and probably avoid converting the whole frontend to TypeScript.
We should be dog fooding our own TypeScript. For all we know there have been attempts to use near-api-js with typescript, which have been abandoned due to the issues that @chadoh brought up.
The types are a crucial aspect of the documentation (as @frol points out bad types make the documentation harder). The other plus that better types have is for configuration. Currently a config object is an any type!
@vgrichina I am always glad to have your opinion, but the question of whether to add a typescript example is different than should a dev choose to use typescript or if we like typescript. We should provide as many examples as possible to help bootstrap need projects.
but the question of whether to add a typescript example is different than should a dev choose to use typescript or if we like typescript. We should provide as many examples as possible to help bootstrap need projects.
@willemneal I'm all for having a TypeScript example. I'm against TypeScript being a default choice for examples. We can have guest-book and guest-book-typescript, etc