In this tutorial you will build an app that creates and displays custom Gadgémon (Gadget Monsters). Custom sprites for your Gadgémon will be generated using OpenAI's DALL-E API and Gadget's built-in OpenAI connection.
After you have finished this tutorial, you will have accomplished the following:
Want to skip to the end? Fork the completed app to try it out and browse the code!
Every Gadget app includes a hosted Postgres database, a serverless Node backend, and a Vite + React frontend. You will use all of these to build an app!
Models in Gadget are similar to tables in a database. They are the building blocks of your app. Models have one or more fields. You can think of fields as columns in a database table. You can create as many models and fields as you need to build your app.
You are going to create a model to store your Gadgémon data, which includes fields to store name, type, what the Gadgémon looks similar to, and an image.
When you create a new model, you get some default fields for your model's records:
You can also add custom fields to your models:
This string field will be used to store your Gadgémon's name. Now you can add additional fields to your model:
These fields will be used to store "type" info as well as a sprite image file that will be generated for your Gadgémon.
Your model should now look like this:
That's it for building your Gadgémon model! Changes to your Gadget apps are automatically saved as you build, so you can move on to the next step.
Now that you have added fields to your Gadgémon model, you need to be able to create new records. Records in Gadget are just rows in a database table. To add new records, you'll need to call your app's API.
Good news! As you build models in Gadget, a CRUD (create, read, update, delete) API is automatically generated for you! This means that your Gadgemon model already has create, update, and delete actions that you can use to interact with your Gadgémon data (and a read action to fetch your Gadgémon data, but that will be covered later). You can see these actions and the code that powers them in the Actions section of the model page.
You will also want to run some custom code when you create a new Gadgémon. In this app, users will enter a name and "similar" string, and pick a type for their Gadgémon. When users click a button in the UI to create their Gadgémon, an HTTP request will be made that returns an OpenAI-generated sprite. You will use the create action to run the custom code required to make this HTTP request.
The Gadget AI app template comes with an OpenAI connection set up with Gadget-managed credentials. This means you can test out the OpenAI API in your app without having to create an account or manage your own API keys. For more information, see our OpenAI connection docs.
A JavaScript file, gadgemon/create.js is already created for you. Now you just need to add some custom code.
This code block has two built-in functions:
The custom code added to onSuccess does three things:
Because your initial Gadgemon record (ie. your name, similar, and type) is already saved to your app's database, you need to use the api from the function's parameters to update this record with a generated sprite image. The api object gives you full access to your Gadget app's API, so you can run any CRUD or custom actions, in this case, the update action is run.
copyURL is a special command used to store files in your Gadget database from a URL. See the storing files documentation to learn more about storing files in Gadget.
Gadget comes with a built-in API Playground where you can test out your backend API. You can use the API Playground to test out your Gadgémon models' create action.
This will create a new record in your model, and send off a request to generate a new sprite image! You should see a success message in the playground, and can hover over the sprite url field to preview your Gadgémon! You can also view your record on the model's Data page.
You can see that your record was stored in the database and that an image was generated. You can view the generated image by copying the url value from the sprite field and pasting it into your browser.
To view the log message you wrote in your action, you can view the Gadget Logs:
You should see the log message that was written when you ran your action. You can make logger calls in code effects at debug, info, or error levels, all of which are useful when debugging your app in both development and production environments.
Now that you know that you can create new Gadgémon records, you can move on to building a frontend so you can create and view your Gadgémon with a UI.
Before we write frontend code, you need to make sure users can make requests to your API from the frontend!
By default, unauthenticated users are not granted access to your app's API. For this app, we won't worry about authentication, but we will need to grant access to the Gadgemon model's read and create actions for unauthenticated users so you can create and view your Gadgemon in the frontend.
Now, requests made to your backend will succeed! Move on to the next step: building your React frontend.
In Gadget, your Vite + React frontend is found inside the frontend folder. New Gadget apps have a starter template that you will edit to build your app frontend:
First, install a component library to style your frontend.
You may have noticed the package.json in the file explorer. Gadget runs on Node.js, so you can install any Node.js package to your app. For this app, we will use Material UI (MUI) to style our frontend.
Run in the Gadget command palette
This will install MUI and its dependencies to your app. Currently, only yarn is supported for package management in your Gadget apps. Once the install is complete, you will be able to see these packages in your package.json file.
Your React frontend will have two main sections: a form used to create new Gadgémon and a list of the Gadgémon that have already been created. Start by adding a section for displaying your already-created Gadgémon.
To display the Gadgémon that was already created, you need to fetch the data from your backend API. You can use the useFindMany hook, provided by the @gadgetinc/react package to fetch all of the Gadgémon records from your backend API. This hook takes in the API client, which you can import from the api.js file in the frontend folder.
The key line to pay attention to is:
The useFindMany hook will read data from your gadgemon model, and return an object that includes:
You can use the objects returned from the hook to display the returned data, a loading message, or an error message to users. In the return block of the provided code snippet, you can see how you are using myGadgemon to display your monsters and fetchingGadgemon to handle a loading spinner.
Now you can see your Gadgémon in the frontend! Just open up your development environment URL in your browser:
And you should see your Gadgémon displayed on the page!
Now add a form to create a new Gadgémon. You can use the useAction hook, provided by the @gadgetinc/react package to create a new Gadgémon record in your backend API. This hook takes in your Gadget API's gadgemon.create action, which you can import from api.js.
Here is the complete code for frontend/App.jsx file. Step-by-step instructions will follow:
Head back to your development URL and you should see your form! Gadget frontends include hot module reloading so the frontend will update as you write code. Try creating a new Gadgémon.
Deploying to production is a two-click process:
Your app will be built and optimized for production, and available at your production URL! To view your app in production:
Your production app will open, and you can create your first Gadgémon in production!
Congrats! You have built your first fullstack Gadget application and have learned how to:
Want to expand your app? Here are some ideas: