Adopting Typescript for XWiki development

Hello all,

I’d like to propose the adoption of Typescript as our best practice language for front-end development.

Motivations for using typescript

Typescript is a typed language with a syntax close to JavaScript, and build to be transpiled to JavaScript. It is also a well-maintained and stable language.

I believe having the ability to manipulate types is of great help both for development and for tool support. Therefore, helping us to write higher quality front-end code.

In addition, the experience of writing 100% of the code in Typescript for Cristal was positive.

Finally, most libraries are now written in Typescript, provide their type definition by default, and provide their documentation in Typescript (e.g., Vue, inversify…)

Where do we want to use Typescript, and where do we want to keep in JavaScript?

Typescript is more useful where a good tool support is available to:

  • typecheck projects
  • generate and export type definitions
  • it’s easy to import types for dependencies

In practice, this means having access to node, a bundler (e.g., vite), and the typescript tsc command. Which means a full node projects.

Therefore, I propose to make the Typescript the advised language for front-end development for modules where node is used as the build tool to produce the JavaScript, distributed by the webjars (i.e., currently xwiki-platform-livedata-webjar and xwiki-platform-notifications-webjar).
On the contrary, I propose to make it optional to use Typescript for existing JavaScript code, where migrating to Typescript is best effort, especially for sources located on modules where node is not available.

Here is my +1, wdyt?
Thanks

Related resources:

+1. I guess this also means we’ll have to:

  • start migrating “JavaScript” modules to use Node for building the WebJars
  • use Node for new WebJar modules

in order to take advantage of using TypeScript. This means reaching a conclusion for Standardizing our use of node in maven projects , because it seems there’s no other (easy) way to use TypeScript without Node. So if we agree to use TypeScript then we have to agree to use Node for JavaScript modules.

Thanks,
Marius

Yes, that’s what I have in mind. Even if we know some part of the code can stay with JavaScript for a long time, the same way we still have some code using prototype.js.

That would be better indeed, though we already have two modules using node for Live Data.

+1, thx

From what I could read, “your existing working JavaScript code is also TypeScript code.” What I understand from this proposal is that we spend some time providing easy ways to use typescript, and later on, we could also set precise JS/TS best practices that do force the use of Typescript by XS contributors in some situations. Is that right?


Do you know if there’s any plan for native Javascript to start supporting some types?

From what I could see on Documentation - TypeScript for JavaScript Programmers , this is the main feature typescript brings. It’d be good to avoid ending up creating customizations relying on typescript just to end up needing to rework them in native Javascript a few years later (pretty much what happened with LESSCSS in our project :slight_smile: – we adopted LESS because it provided powerful tools, those tools got integrated into native CSS and we couldn’t use those fleshed out alternatives because our system was stuck on LESS).

  1. Is there a guarantee that Javascript won’t implement any typing system natively? (maybe because it’s not compatible with the current way Javascript describes variables? )
  2. If there’s no guarantee, in your opinion, for how long can we reasonably suppose native Javascript will not have a typing system as powerful as the one from Typescript?

+1 for the idea overall, I just want to make sure we recognized that this change creates a low criticity long term risk.

Thanks,
Lucas C.

I guess the quote is from TypeScript for JavaScript Programmers.

This is a concise way to express that Typescript is a super-set of JavaScript. Meaning that any valid JavaScript code is also a valid Typescript code. The main difference indeed being that the JavaScript program lacks all the types definitions.

Preferably, otherwise nobody will adopt node.

That part I don’t know. I hope the inherent benefits of Typescript will be a sufficient motivation to adopt it. I’m not sure if we need to make it mandatory.

That’s a good question. I found two ECMA Script proposals going in this direction: GitHub - tc39/proposal-type-annotations: ECMAScript proposal for type syntax that is erased - Stage 1 and GitHub - sirisian/ecmascript-types: ECMAScript Optional Static Typing Proposal http://sirisian.github.io/ecmascript-types/, but they seem relatively old (4 and 10 years old).
I’m not really familiar with how the JavaScript standard evolves, but I don’t think the introduction of types is close.
Therefore, we have quite a few years ahead of us without a suitable alternative.
In my opinion, this makes it worth the effort. The same way as LESS has been beneficial for us until it wasn’t the best option with the evolutions of CSS (that were unforeseeable when we started using LESS).

Apart from what @mleduc already wrote, there is the possibility to specify types with JSDoc comments in plain JavaScript that can be checked by the TypeScript compiler (and by IDEs I assume): Documentation - JSDoc Reference

I guess we’ll see when it comes to using it anyways, but it seems to me like the benefits of Typescript truly shine when maintaining code and not especially writing it. It’s rare that my Javascript code becomes so complex that I forget about the expected type of a variable midway through writing my feature/method. I worry that the lazy solution in most cases is to not write new code with clear types. Some best practices would be a gardrail against everyone settling for this lazy solution.
Thanks for the answer, made the point of this proposal clearer for me :slight_smile:

Okay, thanks for doing the research! Sounds like the advantages far outweight the risk :+1:

That’s good to know.
Pro:

  • easy to migrate back to native JS whenever we’d want to.
    Cons:
  • a bit more wordy than the regular type declaration
  • Not sure yet if you can do everything TS has to offer with those annotations.
  • Not sure how well they are supported by tools that work on typescript. I was thinking that something similar to RevAPI but for Typescript must exist and would be interesting for us.

I think it would be good to agree on a way we want to specify types, once we start writing Typescript. Thanks for the hint :smiley:


Lucas C.