Turning an Existing App into a Mini App on the Base App

Hey everybody, I'm Eric from the base team and today I'm going to show you how to take an existing app and migrate it to a mini app that can be displayed directly within the base app. Let's go ahead and get started. Today I'm going to use the migrate an existing app guide within the mini app section of base docs to walk us through the process of migrating an existing app. based on the prerex you need to have both a existing web app and a base app account. I have my existing web app.

It's just a very very simple hello world nexjs app that's hosted on Versell. So let's go ahead and get started with actually implementing the steps required to migrate this app. First of all, we need to install the miniapp SDK which wraps our app with the functionality required for mini apps. So I'm going to go into the command line and simply run npm install app far caster mini app SDK. I already have this installed.

So then if we take a look at what the next step is, it's triggering app display. When your app is displayed within a miniapp view in the base app, need to let the base app know when it's ready to be displayed. This could be because you are rendering different logic that needs to execute before you want to actually display the app within the base app. A nice loading screen will show for you up until the point that ready is called at which point users will be taken into the landing page of your mini app. The SDK provides a simple action called ready to do so.

Because we're using a React app, we'll follow the React instructions to call ready within a use effect hook to prevent the ready call from being triggered on every single rerender. So, we'll copy the imports and we'll go to page.tsx. For me, page.tsx is the landing page when anyone opens their app.

I'll add the imports. And because we're using the effect, we need to add use client. We'll now add the use effect and it'll simply be SDK.Actions.re.

Given that I don't need to run any logic before the app is ready, I can simply drop in this very simple use effect hook. If you have any logic that needs to render ahead of time, make sure that you have a trigger within the use effect that lets the app know when it should actually be called so that it is then rendered within the mini app view. All right, step two done. Step three, hosting the manifest. The manifest file is a file that lets the base app know about your mini app.

It tells us that you are in fact the owner of that app and it tells us a lot of details that help us display your mini app within the different views whether it be in the feed within search or when friends are sharing it with each other in chat. To host manifest, it needs to be available at your domain.nown/farcaster.json. Because I'm in anjs app, we're going to leverage a route to host the file at that location.

So within app, I'm going to add a folder bewell/farcaster.json. And within this, we'll add a route. And then we're going to drop in the code that we copied. You can see here that we have this note to paste the manifest JSON object here.

Uh this of course is not yet ready. So let's take a look at the next step to get the details. So we provide this example manifest here. It comes with just a lot of dummy data so that you can easily drop in the template into your app. If you're looking to see the full field reference, we have that within our app uh within our docs on docs.

base.org where you can find the details of every single field. So let's go ahead and copy this this template and go back in. We're going to just paste it right here. For your app, you would go through and update each of these fields.

You skip account association and builder address for now. We're about to get into that. Uh, but then each of the values within the mini app object is what you would want to update. For sake of brevity, we'll skip past that now and we'll go on to the next step. The next step is a keystone of turning your app into a mini app and it's creating the account association credentials.

Now these credentials are in your manifest and are used to verify that you are the developer of the application and we can really easily create this credential within baseuild.dev. So you would go to baseuild atbase.dev and you'll sign in. When you're signing in, you're going to be prompted to use your base account to sign in.

So I'm going to sign in with my pass key which requires my phone. Great. Now I've signed in. I've created and added a mini app before. So, I see some data here.

You might just see a prompt to import a mini app. For now, we're just actually going to go to the preview page and account association. And what we'll do is we'll take the URL of our existing app and we're going to paste it and click submit. And you're going to see here that the manifest isn't found. And this is because I didn't push the most recent changes that host the manifest file to production.

So you got to make sure that your manifest the changes you've added are actually in production and live. So I'm going to add these now. Add manifest. And because I'm using Verscell, because I'm using Versell, as soon as I push, Verscell is going to start to deploy the most recent changes for me automatically. I don't need to trigger anything else.

Okay, great. Now that my changes are live, I'm going to resubmit. And you can see that it now finds my manifest. And it recognizes that the account association credentials haven't yet been created. So I'm going to go here and click verify.

And I'm going to sign the manifest to verify my ownership. This is going to prompt me to sign with my account. So once again, I'm going to use my phone to sign with the pass key associated with my base account. And it now returns the credentials. So all I need to do is simply copy these credentials.

go back to the place where I'm hosting my manifest in this route and update the account association. Great. So now we have everything that's required in the account association. One call out is that the signature field because you're signing with your base account will be very long and will look a little bit strange with these leading values, but that is in fact correct and it's because you're signing with your base account, which is a smart contract. All right, now let's take a look at what the next step is.

We'll go back to our docs. The next step is to add the embed metadata. Now the embed metadata is what is used to display your app when somebody shares the URL for your app directly within the feed. This is really powerful and your app needs to have at least the global embed metadata in order for it to be uh discoverable within the base app. So what we'll do is update the Farcaster colon miniapp metadata.

Now within XJS this is really easy. We'll just use the generate metadata function and we'll drop that into our layout.tsx. Now, we see that there's this existing metadata here. So, what I'm going to do is I'm going to copy this down here.

I'll grab the title and description and we're just going to drop it above other. And then here you would add the different values for your app. So, what is the image that you want to have displayed when your embed is shown within the feed? What is the button under the image? There'll be a button that triggers users to open the app.

So, we'll say uh launch hello world. Uh the name we're just going to say hello world. And then the URL we're going to update with the actual URL for our app. And for the splash image, we're going to just leverage in this case what do we have in our public folder? I'll just grab the globe SVG.

Now, usually you want this to be a PNG or a JPEG, but I'm just going to leverage what I get out of the box with my next JS app. Okay, great. So, now we've added the metadata to the embed metadata to our application. Okay, last step uh before we preview the app is to push to production and make sure that all of our changes are live. So once again going to add the most recent changes.

Okay, while that's building in the background, what we're going to use now is the preview tool. We'll go back to base build. And what this does is it allows us to check that the account association is now verified correctly and check that the metadata has been added correctly both from the manifest and the embed metadata. Okay, let's go back to base build now that we pushed those changes to production and we'll retry the account association. Okay, great.

So this time we see that it now verifies it. It grabs my profile eric brown. Grabs my domain, make sure that it's valid and the signature matches. Now let's go ahead and check our metadata. So it has already checked it based off a submit.

Uh so it can see that I've added all of these. Uh you would want to update these to be your own. Uh but within each of these you can also see the description and any restrictions on it such as max length name uh for the name field uh or max length for the web hook URL so on and so forth. So that's great. We now know that it's working with the account association and the metadata is live.

Okay. Now what we can do is we'll use the console which is our preview tool to see a preview of the mini app. So you can see how exactly your app is going to look when it's displayed within the feed. You can see the image of the SVG which is what we decided to use as the background image. Instead you should use a highly curated image of your own.

And then the launch hello world button. You can see in the bottom lefthand corner that ready has not been called yet. And then when we click launch we see the preview show up in the right hand side and ready's been called and we can see hello world and now see our app in the miniab view. So now that we've seen the preview, all that's left to do is to actually publish to the base app. And the way that you do that is simply posting to the base app with the URL for your application.

So as you can see in the screenshot here, you would simply add that, shoot out a post, and it'll be indexed by the base app and publish that it's then discoverable within the feed and within search. With these nine simple steps, you can quickly convert your existing app into a mini app. Happy building. Stay blessed.