Table of contents
Learn how to build a Next.js web application that uses Replicate to run a machine learning model. By the end, you’ll have your own deployed website that can accept text prompts as input and generate images using Stable Diffusion SDXL.
Next.js is a framework for building web applications with JavaScript. You can use it to build apps that have both a Node.js backend web server and a React frontend. It's a great choice for building web applications that use Replicate because it's easy to get started with and it's easy to deploy to Vercel.
The easiest way to get started with a new Next.js app is to use the create-next-app command:
This command asks you to choose a name for your project and some options (you can accept all the defaults), then creates a project directory for you and installs the necessary dependencies. It also takes care of initializing a new Git repository and creating an initial commit with all the added files. This gives you a good starting point for managing your project's source code history.
Now run your app locally to make sure everything is working:
You should have a running starter app at this point. View it in your browser at localhost:3000.
You need your API token to be able to run models. You can set it as an environment variable in your local development environment.
Generate an API token at replicate.com/account/api-tokens and copy the token.
Next.js has built-in support for loading environment variables from a .env.local
file into process.env
.
Create a file called .env.local
in the root of your project:
Then edit the file and add your token to it:
Note: The npx create-next-app
command you ran in Step 1 created a .gitignore
file that ignores .env.local
files. This is a good thing, because you don't want to accidentally commit your API token to your project's source code repository.
Now it's time to write some server-side code that you'll use to run models with Replicate.
One of the great things about Next.js is that you can write your backend code in the same project as your frontend code. Any code in a page.js
file is treated as a frontend component, and any code in a route.js
file is treated as a backend API endpoint.
You'll create two server-side endpoints: one for running the model and one for polling the status of that request until it's complete.
Start by creating a directory for these endpoints:
Now create a file to handle prediction creation requests. Call it app/api/predictions/route.js
and add the following code:
Now create a file to handle requests to poll for the prediction's status. Call it app/api/predictions/[id]/route.js
and add the following code:
Note the [id]
in the directory structure. Next.js has a feature called dynamic routing that treats the id
part of the URL as a variable. You can use this variable in your code by accessing req.query.id
.
You've finished writing the server-side code that talks to Replicate. Now it's time to create the frontend code that renders a form. When a user enters a prompt and submits the form, it posts the data to the server-side endpoint that you created in Step 4. The endpoint runs the model with Replicate and returns a prediction (an object representing a single model run).
Your project already has a file called app/page.js
that renders the default "Welcome to Next.js" home route. Remove all the existing content in that file and replace it with the following code:
The Next.js starter app includes some CSS styles that are used on the default splash page, but they aren't really intended to be reused for a real app.
To create a clean slate for your styles, remove all the content in app/globals.css
and replace it with the following basic styles:
To protect your application from malicious users, Next.js requires some configuration to use external images. Edit the next.config.js
file and add replicate.com
and replicate.delivery
to the images.domains
array:
Your app should be ready to use now! Visit localhost:3000 and enter a prompt to see the results.
Now that your app is working, it's time to publish it to a GitHub repository. This step is not strictly necessary, but it's a good idea to keep your code in a version control system like Git. This will also set you up nicely to use Vercel's GitHub integration, which deploys your app automatically every time you push a new commit to the main branch on GitHub.
First, commit your changes to Git:
Then create a new GitHub repository and push your code to it. You can use whatever flow you like, but here we'll go with the following command that uses GitHub's official gh
CLI to create a new public repo named my-replicate-app
and push your code to it:
If you'd rather keep your repository private, set the --private
flag instead of --public
.
There are many ways to deploy apps to Vercel, but for the sake of brevity, we'll use the vercel
CLI here. Start by installing the CLI and running it:
The command above installs the CLI, then walks you through the process of logging in to Vercel, creating the app, and deploying it.
Once you've deployed your app, you need to add your API token to the remote app's environment variables. This allows your app to make requests to Replicate.
The command above prompts you to enter a value for your token. Paste the same token you used in Step 3. You then need to deploy again:
You did it! You should now have a working web app that's powered by machine learning.
But this is just the start. Here are some ideas for what you can do next:
😎 Show your friends what you've built.
🪝 Update your app to request and receive webhooks so you can do things like store your prediction metadata in a database. See the webhooks docs in the getting-started-nextjs repo.
🚂 Fine-tune and deploy your own customSDXL image generation model and use your new website to show it off.
🔎 Integrate a super resolution model into your new app to upscale the generated images to a higher resolution.
🤖 Explore other models on Replicate and integrate them into your app.
✍️ Update the README if you're planning to open-source your project so others know how to use it and contribute.
⚡️ Connect your Vercel app to your GitHub repo, so you'll get preview deployments for every pull request, and your app will automatically deploy every time you push to the main branch.