Expo Prebuild, Demystified

♪ Expo pre-build demystified. Now, this is a talk not just for beginners, but also advanced Expo users, because I believe the pre-build command is confusing. There's quite a lot of depth to it, and we may have some misconceptions or superstitions about it. So, this talk is going to cover first, what is Expo pre-build? It will introduce you to templates, as it's kind of hard to discuss one without the other. And then building upon that, will teach you how to build your own custom templates. And then finally, we'll bring all those skills together by introducing continuous nature generation.

So, first up, what is Expo pre-build? I think the easiest way to explain this is to just demonstrate what happens when you create an Expo app and then run pre-build on it. So, we'll do that. Run this command, create expo app, we'll just create expo for short, and you'll end up with a folder just like this. What it is, is an Expo Go app based on Expo template default. There are some restrictions with this, though. You can't use native code, or rather the only native APIs you can call are the ones from the Expo SDK. So, just a JavaScript app.

So, what if you wanted to go beyond an Expo Go app? Well, that's where pre-build comes in. You run the Expo pre-build command, and the thing that you will tend to see and that you will tend to be aware of is, this is the command that generates those iOS and Android folders. And the effect of this is it creates a development build. And this is a freestanding app, which is not dependent on the Expo Go client, where you can use any native modules you'd like. And the template that this pre-build is based on is Expo template bare minimum. So, we've got two templates here. What's going on? It's about time we talked about templates.

So, in my mind, there are two kinds of templates. These are not official terms, but I think it helps to discuss it. There's app templates and pre-build templates. We'll go into app templates first. So, app templates provide the starting boilerplate for an app, normally an Expo Go app, but we'll get into that. These will be familiar. There's the default template, which nowadays makes an Expo router app. There's blank, blank type scripting tabs. You know, the ones. An app template will look like this.

You've got an assets folder, you've got your app.js entry point file, and you've got the package.json, of course. Well, one thing that stands out, though, is that it has no Android or iOS folders. So, where do those come from? That's where pre-build templates come in.

Pre-build templates are the templates that provide the native folders. They may also specify some native dependencies in package.json. And there's actually only one pre-build template that I'm aware of. I'm sure there's others floating around out there, but this is the one that comes with the Expo SDK. And this is what it looks like. It's got, as advertised, the Android and iOS folders. It's also got a package.json. But it's got a few other things. Why is that? That's simply because bare minimum can also be used as an app template. If you run create Expo app and you specify the bare minimum template, you can actually make an app from it. And the cool thing about this is that the app you get becomes ready pre-built. You see the Android and iOS folders right there. That's pretty cool. It's not all that much use, because quite often bare minimum is not the app template you want. You maybe want an Expo router app or you want TypeScript or whatever. But just to show you the concept that you can make a pre-buildable app template.

So moving on. This is the meat of the talk. What actually happens when you run Expo Pre-build? It's quite a few things I think you'll find. So let's say we've got an app based off any of those app templates. We call it MyApp and it's missing these Android and iOS folders. So we want to run pre-build to generate them. We'll choose bare minimum as the template to pre-build from. And as discussed, it's got all of those files. It's got a bunch of files that may not come into it, but keep your eyes on the Android and iOS folders in particular.

The surface level knowledge we all know is pre-build copies the Android and iOS folders over if they're missing. If you've already got Android and iOS folders, it will skip that step unless you pass this flag clean, which will delete the Android and iOS folders and then continue as usual. So you can use the clean flag to overwrite your existing Android and iOS folders.

But there's a lot of space left on this slide. So what are all the other things that pre-build does? Well, the first one is quite boring. If the Android and iOS folders have a gitignore file in them, it's actually going to take the details of those, hoist them up to the top level and merge them into the top level gitignore. It also makes sure you've got an app.json if that's missing in your app already. And it's at this stage of the process that if you have any files inside the iOS folder or Android folder, which are named Hello World, or have any content that uses the string Hello World, all of those get renamed to the name of your app. Remember that create expo app also does this when it's creating the app. So when you're creating templates, just remember that you can use the string Hello World as a magic word for something that gets replaced by the user's actual app name and bundle identifier in the right context.

The other thing it does is it upgrades your iOS and Android scripts, if applicable. So if you've already got Expo Go scripts, that's say expo start Android, expo start iOS, these will get upgraded to expo run scripts. What else does it do? It also merges the template, that's pre-built templates, dependencies, into your app's package.json. So any templates that differ between them, it sort of just merges them in. And this is useful if, in your pre-built template, you want to specify some maybe native packages as dependencies. Lastly, actually not quite lastly, it's going to install the node modules and CocoaPods unless you pass this no install flag. And then finally, if there are any config plugins or mods to run, this is the stage at which it will run them, the pre-build step.

So now we know how pre-build works. Let's just learn a bit more about templates while we're here. How would you build your own custom template? First off, let's fork an existing template. So you can take a copy of an existing template, depending on whether you want to work with a pre-built template or an app template.

Let's just go with this expo-template-bare-minimum that lives over here in the Expo monorepo. Make any changes you'd like. And then there's a couple of ways we can share it. Both of these commands, create-expo-app and expo-prebuild, can consume templates. And all you have to do is pass a value for this template flag. It can take one of two formats. It can either be a file path to a local table, which you can make simply using npm pack. Or it can be a URL to a GitHub repository, as long as it's public. Now, this is really powerful. And I think we should be using a lot more of this because it allows us to share some really boilerplate-heavy Expo apps in a really easy fashion.

So a real example of this would be, you run create-expo-app on this template of mine. And you can see each of these different parts of the URL because it's a standard GitHub URL. You can specify a username or repository, a branch and a file path, so it's really flexible. And I'd just like to go over how re-running Prebuild works. So, if you've got a custom template in particular, Expo doesn't remember the last template you pre-built with. So if you pre-built your app from a custom template, just remember to specify that same template in the future when re-running a pre-build. I'll show you what I mean. If you pre-built from a custom template, don't run expo-prebuild-clean because that's going to give you the default bare minimum. Instead, you should run expo-prebuild-clean and specify that same old template or a newer version of that template. So it's your responsibility to maintain an up-to-date version of that template fork.

And using all these skills, we can understand a bit more about continuous native generation. So, first off, what is it? As time passes, your native projects may go out of date. Continuous native generation is the idea of keeping your native projects up to date by regenerating them. And it is heavily suggested Prebuild is the way you should do this. Cha-ching! Cha-ching! So, let's just see what they mean by that. How can Prebuild help you realize this CNG workflow? Now, the bare minimum template updates along with the expo SDK. You'll see a tag for each major version of the SDK. When you run expo-prebuild, by default, it uses the version of bare minimum that corresponds to whatever expo package you have installed. So keeping up to date is simple. You just keep expo up to date, and then you Prebuild each time you update it.

Just make sure it's a clean Prebuild. The last thing is to avoid losing manual modifications, just remember to declare them via expo-config plugins. But if you do lose them it's not the end of the world, because you can just source control your iOS and Android folders. And even if you lose those manual modifications with the Prebuild update, you can try to figure out how to reapply them again. But that's why doing this declaratively saves you a lot of grief.