The Sorcery of Building a Cross Platform Design System Architecture

Hi everyone, I'm Kamlesh. I work as a Principal Product Engineer in the design systems and Infrastructure Tools team, which is part of the Platforms team at Razorpay. So today I'm going to talk about the sorcery of building a cross-platform design system architecture. So disclaimer before I start, this is all about our experience and how we approach this problem space based on the factors and doesn't necessarily mean this is the only way. So let me start first with the problem statement. We wanted a design language system that works cross-platform. Now we started with what are the approaches that we have at hand. The first approach was have individual teams building for each platforms. That's natural. You have different teams, different platforms, and you have different teams who are working on those platforms. And then we started to state the pros and cons of each of the approaches. So the pros for this approach was we have expertise of people for each platform. Let's say a native developer was working on an iOS app. They would have their own set of expertise. And when a web developer was working on the web platform, they'd have their own set of expertise. So we wanted both. And we could also utilize the native capabilities offered by each platform because there are a lot of capabilities that, let's say sometimes native platforms offer you, but the web platform doesn't. Or they have exposed it in a different way. So we wanted to utilize these capabilities natively by each of the platforms. The cons for this approach is multiple teams for building the same thing. You have multiple people who are solving the same problem over and over again. And then we had redundant code for similar things. The third one was less unification of APIs because now your APIs would be redundant or they would be created by different teams. Then there was another approach, which was use react Native Web, of course, which is a very famous option these days. So it had pros, which was you could write once and use across web and native, which is what we were looking for. Secondly was similar APIs across platforms. The cons were react Native Devs to write for web too. Now the challenge is for react Native Devs to debug web things. It's like native first and then pen and paper with web. Now, none of the above fit our needs. We were looking for something that has one same api and will work across web and native. Utilize native capabilities offered by each platform. And then we wanted app devs to do what they are best at and web devs to do what they are best at. So basically our desire Nirvana state was what if a dev had to implement below across platforms? For them, it should be like for us, it would have been like if you take this subcode and copy paste it for both web and native, it should just work. That was like you could say our Nirvana state. So how did we approach this? So we listed down what all things we need to tackle. So the first one was same api that should work across platforms. Then we wanted testing set up because even though you write once and run on both the platforms, we still wanted to test our components on both the platforms individually so that we should not miss any of the bugs on either of the platforms. And then we wanted to bundle each platform separately so that your web bundle is not messed up with react Native and vice versa because otherwise it will just break. And we also wanted to ship TS types along with each of these individual bundles. Yes. So let's see things in action by implementing a typographic component. So this is the component that we'll implement and it should work as it is on both the platforms. This is basically an end state that we will be doing during this session. Now let's start with the first one. Same APIs that work across platforms. So if you think about it, the api for this would look something like, let's say if you want to design or create a typographic component, what would the api look like? It would have ID, color, font family, font size, font weight. These are the very basic properties for a typographic component. So usually what you'll do is you'll start with implementing platform by platform. So the obvious first thing to start is let's just start implementing it on web. So we are using style components. So we just define the styles and then we just render the style text and return it. And then we basically export it. Then we come back to native. We kind of again define the styles and how it will render. And now just move forward. But there's something that is going on over here. Let's figure out what's going on. So if you see this part of code that is being highlighted and this part of code, both of these are same. The only difference between both of these things is the top thing, which is basically your imports, where you are importing, you're using, rendering a style.div on web, but we are rendering a style.txt on native. So this is the only difference. This is not what we wanted. This is not what we wanted. So let's see what we can do to make it better. So first we'll extract the styles. We'll just see that, okay, the styles are common. We'll just create a function that will accept certain arguments and then just return it. These are basically our styles. Now let's do a refactor. So this part, which is common in both web and native, we'll just remove it and replace it with our newly created getTextStyles function. Now next we want to expose something below for our consumers. This is the step three. The consumer should just say import text from design system. Now whether it should be a web component that we want to return or we want to return a native component, that should be the abstraction and that should be handled by the tooling or the platform that we are creating. So that's basically the responsibility of the design system team. So how do we turn this concept into reality? How do we achieve something which is like, you say import and the platform should directly identify? So we use the power of file extensions and bundlers. Now before we dive into that, I want to talk about how Metro, which is basically a bundler for react Native, resolves files as of today. So let's say whenever you say import file name from file name, Metro will first start with looking at the file extension, which is basically, is there a file name which exists with let's say.android.ts? If yes, resolve it. If not, then go back to, then go to ios.ts. If not, then go and see if.native.ts exists. If it doesn't, then fall back to.ts. This is something that Metro does right now. So it allows you to implement things which are specific to Android or specific to iOS, which is a very basic requirement and sometimes you need it. What if we steal this idea and steal it, steal this idea to make it work on web? Let's see how. So webpack has this config which says resolve extensions. This is an array which defines the priority order for the files to be resolved. Now what we'll do over here is we want to tell webpack that you are doing whatever you want to do, like ts, tsx and everything. What we will do is we'll put.web.ts and.web.tsx. So the priority order is basically the way you define the elements in the array. Now webpack works basically whenever you say now import file name from file name, it will basically go and say, okay, file name.web.ts, does it exist? If yes, resolve it. If it doesn't, then go and just pick file name.ts. So now after we do this, what we have to do is we want to rename our files so that our platforms or our bundlers are able to pick the specific file for that particular platform. So what we'll do is we'll say text.web.tsx and we'll say text.native.tsx. And then we'll have of course an index.tsx which will just do export text from text. Now let's see if things are working so far. I'll just switch to VS Code and we'll just say text. So this is basically the text component that we are basically working on. So you'll see this is text.native, this is text.web and then we have index. Now let's see if things work. So things are rendering as we wanted them. Let me also show the native part. So things are working absolutely fine. But if you look at this, there's a tiny error which says cannot file module text or its corresponding type declaration. Now the thing is we made our bundlers understand how to resolve these files but typescript still doesn't know. Now the way to come around or solve this error is what we can do is we can define declarations and we can just say export text from text.web. And things should work. Sorry, my bad. We need to say text.t.tsx. And yes, this would work. This error is gone because now typescript is happy. Whenever it says it knows it's okay, whenever you click on it, it knows okay fine, I need to resolve it from here. So typescript is happy. Our outputs are rendering. So let's get back. So basically if you see, we had configured the bundlers but then to make this work we kind of defined our declarations. So coming back to our checklist, we have same api that is working across platforms, at least a bare minimum version. Now let's move to the second item in our checklist, testing for both the platforms. Now we are using react testing library, so let's set up Jest for testing for web because if you remember I was saying that we need Jest to test for both the platforms. We want to test for web and we also want to test for native. So starting with the web config for Jest, what we are trying to say Jest is that just include web extensions thing and ignore all the native.test files. Similarly for native we are doing the reverse. We are saying that ignore all the web.test files and include only the native extensions which are ending in.native files. Now let's write up some tests. So we created a text component right now. We just write a test for it. So this is just a basic extracted component for testing. Now let's see cross platform magic. So we will create a file called test.web.test.tsx which will basically use the Jest arm and render it using the renderer that the react testing library provides. And similarly we will do it for native. Now let's see if the test actually works. So test, we will say react. So it's running. Finally. So our tests are working for web. Now let's see if this works for react Native as well. All right. So the tests are passing which means things are working fine. The native is doing what native platform is supposed to test and the web is testing for the web platforms. Let's move ahead. So testing is done. Now let's bundle each platform separately along with our typescript types. So what should we use to bundle our design system for both web and react Native? We'll use Rollup. But can Rollup bundle react Native libraries? Yes, it does. So the first step would be to configure Babel. So this is our Babel config. First we'll define the plugins and the presets for react Native. So this config is just an object that we are creating right now. It has a key called react Native. Similarly, it has a key called react. Now what we'll do is when we are exporting, the way we export is we read an environment variable called framework and based on what framework is passed as an environment variable, we'll export that particular Babel config. Just hold on to that environment variable. We'll come back to that. The second step is configuring Rollup. The way we did for Babel, similarly we'll do it for Rollup as well. We'll define two configs. First we'll start with react Native. We'll define the input as index.ts and then the output would be index.native.js. Just pay attention to this particular thing. Similarly, for react, we'll just say the output file is index.web.js in the config. And then we'll add scripts to our package.json, which we'll just say we'll have two scripts, which is build react and the second is build react Native. If you see here is the environment variable that we are passing. We say framework is react for react and framework is react Native for react Native script. But let's see how all this works. Let me show you or let me help you to visualize how these things would work. First, when the script would run for build react, what it will do is it will first set the environment variable to react, which will then act as an input to the Babel config, which will just understand, okay, you know, I need to export my react config. And then next step would be Rollup. So it will just read the environment variable and it will return the react config, basically web config for Rollup. And after that, it will just go like once you run this, it will just go and create a bundle, which is index.web.js. And similarly, it will do for react Native. And what you'll get is react Native.js. So let's build it in action. We'll just go back to our browser. And we'll just run the build yarn build. Just go do a bunch of things, create everything. And it is creating the builds. Okay. So if you see, we have basically we are able to create the bundle, which is .native and the.web one, which is basically that we are able to create what we wanted. Let's go back. But wait, what about types? Our types are co-located alongside of our components if you would have seen. But we bundle the components into a single bundle. But we are not bundling the types. What do we do? So we need to bundle our types in the same structure as our library bundle. But wait, how are we going to do it? Again, roll up to the rescue. So remember our old config where we had react Native and react? What we'll do is we'll enhance it and we're going to use a plugin called declarations. We will do a rollup plugin declarations. What it does is it's basically it will just generate a bundle of your declaration files. So the input is index.d and it will generate to your build file side by side to our actual builds. So this is what it will look like, the final structure. Let me go back to the code quickly and let me add this bundle. And let me run the build again. It's running, it's running, it's running. All right, it's done. So now if you see, we have these types, right? And if you open it, it has all the declarations that we exported or we wanted. So since it's side by side to your index files, your intelligence, everything would just work. And that's basically what we wanted. So one thing to emphasize is we need only one type bundle because we have the same api across platforms, right? Remember that's basically what we started off with. So coming back to our checklist, we have same api, which works across platform. We have testing set up that will test for individual things so that we don't miss on any bug while we are trying to achieve cross platform. And then we are able to bundle for each platform along with the typescript types. But wait, what about accessibility? Let's talk about accessibility. So there are some native and web accessibility props, right? On react natives, it's a communication called accessibility role description versus on web, it's called area role description. Then we have accessibility label on react native, but on web, you have like area label. So these are like bunch of differences. So taking the same approach as our components, we will kind of create two maps, right? Which will have like an alias, that's a label required hidden invalid in this example. And we kind of give it the respective values for each platform. So these are two maps. And then we put it into two different files, which is accessibility.web.ts and.native.ts. Then we'll throw a function on top of it, which will be resolved or which will be used at runtime. And it will just say, okay, if you are actually at build time, and it will just say that, you know, you're building for web or you're building for native, based on that, it will just do a lookup and give you the respective prop name. Let's see it in action. We'll just again take the typography component that we built and we'll import our make accessible function, pass it the accessibility prop. And if you see at the bottom, this is what you'll get, right? It will just give you the prop, which for that particular platform. So it will just say text role. You'll just say text role heading, and it will just do a render area role on web and just roll on react Native. So yeah, that's basically what we wanted, right? Your accessibility is also sorted. So let's do a quick recap. So we started with single api to rule them all. We utilized the power of file extensions, that is web and native. And then we abstracted all the common things which are platform independent, right? So let's say if it's for things which are common, let's say styles that are common, we kind of abstracted it into a get textiles. We kept platform specific logic within web and native files. For example, if you want to pass a prop called as, which doesn't exist on native, what you would essentially do is throw an error on native platform. So you could put that logic in this web and native files. We configured our tools, which is metro, webpack, rollup, jest, ES, and typescript to resolve appropriately. So again, we are just utilizing or leveraging our tools to their best. We rebundled for each platform individually using rollup. We generated single types bundle using rollup again. So yeah, that's all I had to talk about. I hope you had fun. The code, the demo that I showed is on GitHub. You could just go to my profile. It's called cross platform design system. And you could just go and visit our design system, which is played, which is also open source and you could see everything in action and it's just working absolutely fine. That's all. Thank you.