Make it simple for developers to use Upstash on an site hosted on Netlify and provide useful code snippets that use the environment variables we will create automatically once connecting to a users' Upstash account.
For this integration the flow should be relatively simple.
- Collect the users’ Upstash API key and email address and store it
- Create a flow for the user to select and integrate with an Upstash Redis database. This will trigger the logic to create all the necessary environment variables to connect to this database
- Once an Upstash Redis database has been integrated with, the user will be able to copy code snippets that show them how to connect to that database instance via their application
Whilst we write this integration, we are going to run a local server to preview the integration. We can run this with npm run preview and visiting https://app.netlify.com/ui/preview/netlify-upstash-integration?server=http://localhost:8899. On this preview page, you can select a site that you want to test the integration on and refresh the preview each time you introduce new elements to the integration.
As we will be storing the users' Upstash configuration with the Integration API, we need to define the shape of our integration context and we do this by creating a zod schema to define the shape of this context. For this integration, our config will be relatively simple and can be found here
We can then define a type definition that all of our API handlers will use, so that when using the context argument we know what the object will look like.
Based on the designs, we are going to have two routes:
- Root integration page -
/ - Integrate database page -
/integrate-database
The root integration page will be the page where the user lands when they enable your integration. For this example it would be, https://app.netlify.com/sites/<site-name>/integrations/database/upstash.
The /integration-database route is where users will land when they have clicked the CTA to add a new database to the integration, taking them to: https://app.netlify.com/sites/<site-name>/integrations/database/upstash/integrate-database.
In our / route, we need to collect the API key and email address of the user for Upstash. This is where we make use of the components made available to use with the Netlify SDK. We use these components to collect the users' Upstash configuration using a form, which will then make a call to an API handler we will create in the next step.
Next we create and register an API handler to receive the configuration from the above form with the integration.addApiHandler() method and make use of the NetlifyIntegrationClient that is made available in the context argument that is passed to our API handlers.
We call this API handler from the configuration form we created and refresh the page once we get an ok response from the API handler.
Once a user has connected to their Upstash account via the integration, we are able to create a call to action (CTA) to navigate users to a new route to start integrating with their Upstash Redis database. This means, we need to conditionally render elements on the page based on whether the user is connected or not. The Integrate database CTA is placed within a card, but we keep the display property of parent card element set to hidden so that we can add some logic in the next step to show this conditionally. We also make our connect-form hidden by default too.
To make elements conditionally render with the SDK, we use the onLoad function that is made available to each surface route. For this this onLoad function to know the current context of a users’ integration, we will need to create and make a call to a status API handler. This handler will simply tell us, if we’re connected and will also return a list of databases that have been integrated.
We can call this handler and then use the picker, that is part of our SurfaceState, to change the visibility state of elements.
In our /integrate-database route, we allow users to select from a dropdown of their Redis databases they have created in Upstash. We add a form with an id of integrate-form with a select field that will hold the databases the user can integrate with. As with our / route, this route will also need an onLoad function to populate this select field with databases from the users’ Upstash account.
The onLoad makes a call to a new API handler called get-databases which contains the logic to use our saved integration context to make an authenticated call to Upstash to get the users' Redis databaes. The response is then used to populate the options in the select field.
When we submit our integrate-form, we can effectively integrate the database by saving the Upstash endpoint and token as environment variables for the user and storing the id of the database we have integrated within our integration context. This is achieved by calling another API handler called integrate which is responsible for updating our integration context and saving the environment variables.
Now that we’ve built the flow for integrating with a users’ Upstash databases, we can give them helpful code snippets in the integration UI. This will help guide users in quickly making use of the integration and the environment variables we have created. We add a dropdown in our / route which will show all of the integrated caches and when an option is selected from this dropdown, we make our code snippet element visible.
If you want to use this integration as a template for building your own or just want to deploy this integration yourself so you can see it working, just click the deploy to Netlify button below.
