Automatically maintaining thousands of code demos across multiple framework variations

Rate this content
Bookmark

At AG Grid, we maintain thousands of code demos, with the same demo in Angular, React, Vue, and Vanilla JS. Additionally, each framework has different variations covering JavaScript, TypeScript, Modules, Packages, Hooks, Classes, Vue 2, and Vue 3. How do we do it? We automate. This session will explain how we start with a single TypeScript version and automatically convert it to every combination we need and finally use Cypress to test the converted example.

7 min
16 Jun, 2022

Comments

Sign in or register to post your comment.

Video Summary and Transcription

The talk focuses on creating the best JavaScript data grid by categorizing code using abstract syntax trees. Code files are represented as tree structures, allowing for the extraction of different sections. Framework-specific converters generate code examples for Angular, React, and Vue. TypeScript validation and testing ensure code quality and easy updates for framework examples.

1. Introduction to Code Demos and Categorization

Short description:

Our aim is to make the best JavaScript data grid in the world. We have about 500 demos and 8,000 demos in total. We want to write a single example in TypeScript and categorize the code using abstract syntax trees.

Can I ask you a question before I start? How many of you would be happy at your job if they asked you to maintain thousands of code demos? For me, you are happy. There's probably a good job for you in writing docs. But for me, you know, that's not what I want to do. And that's a situation I found ourselves in at aggrid.

Now our aim is to make the best JavaScript data grid in the world. But we understand, as Rich was talking about earlier, that our grid is only going to be as good as what our users can do with it, and the way we can show them what they can do is via our docs. So we are determined for every feature that we have to have a live code demo. So you'll see what the grid does. And you'll also see the code that is powering that demo.

So if we just start adding in all these examples for our features, we've actually got up to about 500 demos now, and you think that's bad enough. Wait till you realize the AG grid is agnostic. So we support JavaScript, TypeScript, Angular, React, you can use hooks and classes, you can write it in view two, view three. And we want you, when you're using our docs, to be able to see the code in the framework that you're using. So you times all these numbers together, and we end up with about 8,000 demos. So there's no way, even if you do want to do it, that you're going to be able to keep up and not make mistakes with copy and paste. And it's just going to be quite boring, to be honest.

So in an ideal world, what we want to do is write a single example, and we're going to do this in TypeScript, because for Angular, we need types. If you want React with TSX, you need types. For our JavaScript example, we just strip the types out and we're done. And then we can use that as a starting point for our view and React with just plain JavaScript. Now, the first step to be able to achieve this is to categorize your code. So here we've got some example AG grid code. We've got some static config. We've got a callback and also an external event. And the reason we need to categorize this is so that we can apply framework-specific converters to each of these specific areas. Because we know that Angular uses different syntax to react. And it's different depending on what you're trying to achieve. But then the challenge and the question is, how do we programmatically categorize our code example? And that's where abstract syntax trees come in. Because we can represent any piece of code as a tree. So, for example, the highlighted function here is size to fit.

2. Generating and Maintaining Framework Examples

Short description:

We represent code files as a tree structure using abstract syntax trees. By parsing the code with TypeScript, we can extract different sections like properties, methods, and event handlers. Framework-specific converters allow us to generate code examples for Angular, React, and Vue. We validate the code with TypeScript and perform testing to ensure quality. This approach enables us to update framework examples easily and provides users with code that matches their chosen framework.

And that's represented as a function definition with a property of name, parameters, and the body. And any code file that you've got, you can break it down and represent it in this tree structure.

So, for example, if you're using type script to parse it, you give it the source text of the example and it will give you this AST. And then we're gonna traverse this tree and use pattern matches to pull out all of these different sections. So, we'll find what's a property, what's an instant method, and what's an event handler.

So, this is an example of what one of these pattern matches might look like. So, we've got... Is this a function call? So, we run through all the nodes in the tree, and if it's a function call, then we pull it out into this external event handlers where we've got the name, the parameters, and the body. So, we build up this memory model of what the code example actually looks like. And then we use our framework-specific converters. So, here we can see Angular and Vue. You've got the different syntax for trying to achieve a similar thing. And so, we use these framework-specific converters against each category. And once you've done that, you can spit that code out into a base template, and you find you've got your Angular, React, and Vue examples.

And we have only written the TypeScript one along with these converters. Just to make sure we haven't made a mistake, we validate it with TypeScript. We hit every single one of these examples with Cypress to make sure there's no errors, a bit of snapshotting for visual regressions. And if we're feeling really keen and careful, we can git diff the entire repo to make sure we haven't done anything silly. And the result for us is that we're able to update all our framework examples in one place. For example, we added support for React and TypeScript, and it only took a day, but there's 500 examples there. If we want to add a new framework support, we'll just add one converter. And we're happy developers because we're not maintaining all of these examples, and there's more time for us to work on features. And I believe our users are happier because they can go to our docs, say what framework they're using, what variation they're using, and they get to see the code that matches that to copy and paste into their application.

So for you as takeaways, I want you to realize this point, that we can use TypeScript abstract syntax trees to generate and reason about our code. And a great way to get started with this is astexplorer.net. Just drop your code into that, and it will show you what the abstract syntax tree looks like. And, finally, don't manually maintain something that you can generate. If you do take inspiration from this work, I'd love to hear what you end up building with it.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

TechLead Conference 2023TechLead Conference 2023
35 min
A Framework for Managing Technical Debt
Let’s face it: technical debt is inevitable and rewriting your code every 6 months is not an option. Refactoring is a complex topic that doesn't have a one-size-fits-all solution. Frontend applications are particularly sensitive because of frequent requirements and user flows changes. New abstractions, updated patterns and cleaning up those old functions - it all sounds great on paper, but it often fails in practice: todos accumulate, tickets end up rotting in the backlog and legacy code crops up in every corner of your codebase. So a process of continuous refactoring is the only weapon you have against tech debt.In the past three years, I’ve been exploring different strategies and processes for refactoring code. In this talk I will describe the key components of a framework for tackling refactoring and I will share some of the learnings accumulated along the way. Hopefully, this will help you in your quest of improving the code quality of your codebases.

React Summit 2023React Summit 2023
24 min
Debugging JS
As developers, we spend much of our time debugging apps - often code we didn't even write. Sadly, few developers have ever been taught how to approach debugging - it's something most of us learn through painful experience.  The good news is you _can_ learn how to debug effectively, and there's several key techniques and tools you can use for debugging JS and React apps.
React Advanced Conference 2021React Advanced Conference 2021
19 min
Automating All the Code & Testing Things with GitHub Actions
Top Content
Code tasks like linting and testing are critical pieces of a developer’s workflow that help keep us sane like preventing syntax or style issues and hardening our core business logic. We’ll talk about how we can use GitHub Actions to automate these tasks and help keep our projects running smoothly.
React Advanced Conference 2022React Advanced Conference 2022
22 min
Monolith to Micro-Frontends
Top Content
Many companies worldwide are considering adopting Micro-Frontends to improve business agility and scale, however, there are many unknowns when it comes to what the migration path looks like in practice. In this talk, I will discuss the steps required to successfully migrate a monolithic React Application into a more modular decoupled frontend architecture.
DevOps.js Conf 2022DevOps.js Conf 2022
33 min
Fine-tuning DevOps for People over Perfection
Demand for DevOps has increased in recent years as more organizations adopt cloud native technologies. Complexity has also increased and a "zero to hero" mentality leaves many people chasing perfection and FOMO. This session focusses instead on why maybe we shouldn't adopt a technology practice and how sometimes teams can achieve the same results prioritizing people over ops automation & controls. Let's look at amounts of and fine-tuning everything as code, pull requests, DevSecOps, Monitoring and more to prioritize developer well-being over optimization perfection. It can be a valid decision to deploy less and sleep better. And finally we'll examine how manual practice and discipline can be the key to superb products and experiences.

Workshops on related topic

React Summit Remote Edition 2021React Summit Remote Edition 2021
87 min
Building a Shopify App with React & Node
Top Content
WorkshopFree
Shopify merchants have a diverse set of needs, and developers have a unique opportunity to meet those needs building apps. Building an app can be tough work but Shopify has created a set of tools and resources to help you build out a seamless app experience as quickly as possible. Get hands on experience building an embedded Shopify app using the Shopify App CLI, Polaris and Shopify App Bridge.We’ll show you how to create an app that accesses information from a development store and can run in your local environment.
JSNation 2022JSNation 2022
41 min
Build a chat room with Appwrite and React
WorkshopFree
API's/Backends are difficult and we need websockets. You will be using VS Code as your editor, Parcel.js, Chakra-ui, React, React Icons, and Appwrite. By the end of this workshop, you will have the knowledge to build a real-time app using Appwrite and zero API development. Follow along and you'll have an awesome chat app to show off!
GraphQL Galaxy 2021GraphQL Galaxy 2021
164 min
Hard GraphQL Problems at Shopify
WorkshopFree
At Shopify scale, we solve some pretty hard problems. In this workshop, five different speakers will outline some of the challenges we’ve faced, and how we’ve overcome them.

Table of contents:
1 - The infamous "N+1" problem: Jonathan Baker - Let's talk about what it is, why it is a problem, and how Shopify handles it at scale across several GraphQL APIs.
2 - Contextualizing GraphQL APIs: Alex Ackerman - How and why we decided to use directives. I’ll share what directives are, which directives are available out of the box, and how to create custom directives.
3 - Faster GraphQL queries for mobile clients: Theo Ben Hassen - As your mobile app grows, so will your GraphQL queries. In this talk, I will go over diverse strategies to make your queries faster and more effective.
4 - Building tomorrow’s product today: Greg MacWilliam - How Shopify adopts future features in today’s code.
5 - Managing large APIs effectively: Rebecca Friedman - We have thousands of developers at Shopify. Let’s take a look at how we’re ensuring the quality and consistency of our GraphQL APIs with so many contributors.
DevOps.js Conf 2022DevOps.js Conf 2022
152 min
MERN Stack Application Deployment in Kubernetes
Workshop
Deploying and managing JavaScript applications in Kubernetes can get tricky. Especially when a database also has to be part of the deployment. MongoDB Atlas has made developers' lives much easier, however, how do you take a SaaS product and integrate it with your existing Kubernetes cluster? This is where the MongoDB Atlas Operator comes into play. In this workshop, the attendees will learn about how to create a MERN (MongoDB, Express, React, Node.js) application locally, and how to deploy everything into a Kubernetes cluster with the Atlas Operator.
React Summit 2023React Summit 2023
88 min
Deploying React Native Apps in the Cloud
WorkshopFree
Deploying React Native apps manually on a local machine can be complex. The differences between Android and iOS require developers to use specific tools and processes for each platform, including hardware requirements for iOS. Manual deployments also make it difficult to manage signing credentials, environment configurations, track releases, and to collaborate as a team.
Appflow is the cloud mobile DevOps platform built by Ionic. Using a service like Appflow to build React Native apps not only provides access to powerful computing resources, it can simplify the deployment process by providing a centralized environment for managing and distributing your app to multiple platforms. This can save time and resources, enable collaboration, as well as improve the overall reliability and scalability of an app.
In this workshop, you’ll deploy a React Native application for delivery to Android and iOS test devices using Appflow. You’ll also learn the steps for publishing to Google Play and Apple App Stores. No previous experience with deploying native applications is required, and you’ll come away with a deeper understanding of the mobile deployment process and best practices for how to use a cloud mobile DevOps platform to ship quickly at scale.