Introducing TypeScript to our front end stack

<%- if @topic_view.topic.tags.present? %>
<%= t 'js.tagging.tags' %>: <%- @topic_view.topic.tags.each do |t| %> <%= t %> <%- end %>
<% end %>

With Silverstripe CMS 4, we modernised the way we build the frontend code for the CMS:

  • We adopted yarn to manage our third party JS dependencies,
  • We adopted webpack and ES6 to better manage our Javascript code,
  • We adopted React for some parts for of the CMS UI,
  • We switch to using Bootstrap/Reactstrap for the CMS UI,
  • We switch to writing our style sheet in SASS rather than plain CSS,
  • We’re using GraphQL as the primary means of communication between the CMS frontend and backend.

We’ve also been phasing out some of older tech like:

  • JQuery,
  • Entwine,
  • SS templates in the CMS administration area.

These changes have helped the Silverstripe CMS team build richer UIs more quickly. We also find that more and more of our UI is implemented in Javascript rather than in PHP or SS templates. Because of this our Javascript codebase is growing and becoming more intricate.

This is leading to some challenges:

  • Our JS API is not as formal as our PHP APIt,
  • We build lots of abstraction in our JS codebase, but we don’t have a good way of documenting how to use them,
  • JavaScript/ES6 doesn’t have a lot of tools to deal with types out of the box.

As a possible way of dealing with those challenges, we’ve been experimenting with TypeScript. TypeScript is a typed superset of JavaScript … In simpler terms, TypeScript is essentially JavaScript extended with extra structures to help manage type information. TypeScript can not be run directly instead it needs to be transpiled back down to regular JavaScript.

Because it supports structure like interfaces and abstract classes, it would help us properly define how to interact with the Silverstripe CMS front end codebase. TypeScript can also explicitly warn us when we’re not using the correct types and provide better code hinting.

Most importantly, TypeScript can be used side-by-side with regular JavaScript, so we could progressively introduce it to our existing front end codebase. Because TypeScript transpiles back down to JavaScript, if you’ve developed a module to customise the Silverstripe CMS interface, it should still work without any changes.

We haven’t made a decision yet. We’re curious to know what level of interest the Silverstripe community has with TypeScript. More generally, we would like to know how comfortable people are with customising the Silverstripe 4 CMS interface:

  • Are you writing new React components and injecting them in the Silverstripe CMS?
  • Are you overriding Silverstripe style and changing CMS behaviour with JQuery/Entwine?
  • Are you overriding core Silverstripe SS templates?

Leave your thoughts on this thread and/or fill our Silverstripe CMS UI development survey.

We also have an RFC and experimental PRs that adds TypeScript support to Silverstripe CMS. Head over to GitHub if you would like to get your hands dirty and try it out.

@MaximeRainville Computer says no on that CMS UI survey

47%20am

I haven’t used TypeScript yet but I’d like to learn it so I wouldn’t mind seeing it in Silverstripe CMS.

I haven’t really been a fan of the gradual phasing in of React in the CMS though. It sounded good on paper, but now the docs are kind of fragmented (or missing) and things that used to work everywhere only work in some places. Here’s an example - developers expect File::getCMSFields() to get the CMS Fields (because it used to and the API still says it will), but actually a Factory is used for that now.

Another example - custom yml translations work for some modules, but for others you need to hack in some javascript.

Having the old and new co-exist makes it really hard to comprehend how things work in Silverstripe. Naturally that makes it hard to document as well. It also means that you often have to learn SilverStripe conventions and techniques a couple of times over - once for the old parts of the CMS and again for the new part. It feels like the barrier to entry to being a SilverStripe hacker keeps getting higher and I can imagine new users could get confused and overwhelmed pretty quickly with this melting pot of old and new tech and contradictory documentation.

Sorry, I know this is a rant and is going way off-topic. But personally I’d rather new conventions like this were introduced only in major versions and applied throughout the codebase, so there’s only one (right) way of doing things. I want new versions of SilverStripe to be as transparent and appealing to new developers as it was to me 10 years ago. I think for the project to thrive long term, making it an easy (read: consistent) framework to pick up for new users is more valuable than providing an easy upgrade path or regularly shipping new features in minor versions.

Surprised myself a bit with those answers. I think that having these dual systems in place has made me stop using either of them. I don’t want to do things the old way because I know it will be replaced at some point, and I don’t want to learn the new way yet because I can’t use it everywhere and it’s still marked as an experimental API.

4 Likes

Oups … I forgot to share the Survey outside of Silverstripe Ltd. Should be fixed now.

2 Likes

Yeah when I joined the CMS team, it took me a while to wrap my head around how the React stuff is meant to interact with the Entwine stuff and vice-versa. I’ve been working here for almost 3 years now and there’s still parts of that interaction that are somewhat nebulous to me.

Part of the problem is that we’ve got many stakeholders to please. And it’s difficult to justify to people paying the bills that we’re going to spend several months refactoring the CMS UI to be a pure React app, but it’s going to look exactly the same and behave exactly the same way.

But that’s great feedback … that’s exactly what I was looking for.

2 Likes

Interesting to hear @JonoM that you’ve basically stopped customising the UI - not an ideal situation. I’ve also found the split approach challenging. I am very enthusiastic about moving to modern JS framework as the way to customise the UI and have been writing all of our new fields in React but it has been difficult. I think this stems from the lack of docs and/or formal API for JS. Also, the parts that were moved to react were the asset admin - 90% of the time i want to customise something - it is in the standard ‘page edit’ screen.

As for typescript - I like it but I don’t think it is the silver bullet for a formal API. As you mention @MaximeRainville it is backwards compatible so In a way it wouldn’t really affect anyone who isn’t contributing to core? I’ve seen recently that cypress (testing framework) is migrating their entire codebase to typescript (from coffee script) could be useful to see how that process is working for them.

1 Like

Yep, a potential issue though is that it could discourage people from contributing to core because it’s yet another thing people have to learn. Probably worth the risk for the benefits but just something to consider.

BTW I’m not anti React or TypeScript at all - I’m also excited about these new technologies. And it might be totally impractical to migrate the codebase to these new conventions all at once. I guess CMS 3 was all old (Entwine), CMS5 will be all new (React), and CMS4 is a mixture. So while the evolution of CMS 4 has made it feel like a product for SS veterans, CMS 5 might be the clean and modern codebase that newcomers can fall in love with.

I think I’ve said before somewhere that I’d love major CMS releases to alternate between focusing on features (revolution) and stability (iteration). In that case v4 would definitely be a feature-focused release and intended for people who want to use the latest and greatest. v5 would be the culmination of v4 development efforts, an optimised version with light API changes to clean up things that turned out to be bad ideas in v4 but couldn’t be changed for SemVer reasons. If there were to be a LTS option, it would be v5, and minor releases would be far less ambitious (and less risky) in v5 than they have been in v4. Then you could start overhauling major things again in v6.

1 Like