Published on

Next.js and FastAPI: Build a Full-Stack App in 30 Minutes

Building a full-stack application with Next.js 15 and FastAPI (a high-performance Python framework for building APIs) typically takes less than 30 minutes to set up. By using Next.js for the frontend and FastAPI for the backend, you create a powerful system where your user interface stays lightning-fast while your Python logic handles data processing. Most developers can deploy a basic "Hello World" version of this stack in under 10 steps using modern cloud platforms.

Why combine Next.js and FastAPI?

Next.js is a React framework that handles the "client-side" (the part users see) of your app. It provides built-in routing and image optimization to make your website feel snappy.

FastAPI handles the "server-side" (the hidden logic) using Python. It is famous for being incredibly fast and automatically creating documentation for your code.

We've found that this combination is the most effective way for solo developers to build AI-powered apps. Python has the best libraries for AI, while Next.js offers the best user experience for web visitors.

What do you need before starting?

You will need a few tools installed on your computer to follow this guide. Make sure you have the following versions or newer:

  • Node.js 20+: This runs the JavaScript code for your frontend.
  • Python 3.12+: This runs your backend logic.
  • A Code Editor: Visual Studio Code is the most popular choice for beginners.
  • Terminal Access: You will use the Command Prompt, PowerShell, or Terminal to run commands.

If you don't have these, you can download Node.js from its official site and Python from the Microsoft Store or Python.org.

Step 1: How do you set up the Frontend?

First, you need to create the folder that will hold your website code. Open your terminal and type the following command:

npx create-next-app@latest my-awesome-app

The terminal will ask you several questions. For a beginner-friendly setup, choose these options:

  • TypeScript? Yes (it helps catch errors early).
  • ESLint? Yes.
  • Tailwind CSS? Yes (it makes styling your site easy).
  • src/ directory? Yes.
  • App Router? Yes (this is the modern way to build Next.js apps).

Once the installation finishes, move into your new folder by typing cd my-awesome-app. You can start the frontend by typing npm run dev.

Step 2: How do you set up the Backend?

Now, you need a place for your Python code to live. It is best practice to keep this in a separate folder inside your project.

Create a folder called api and move into it. Inside, you should create a "Virtual Environment" (a private space for your Python tools so they don't interfere with other projects).

mkdir api
cd api
python -m venv venv

To use this environment, you must activate it. On Windows, type venv\Scripts\activate. On Mac or Linux, type source venv/bin/activate.

Step 3: How do you install FastAPI?

With your virtual environment active, you need to install the software that makes FastAPI work. You will need the main framework and a "server" called Uvicorn to run it.

pip install fastapi uvicorn

Create a new file inside the api folder named main.py. This file will hold your backend logic. Paste the following code into it:

from fastapi import FastAPI

# This creates the main application object
app = FastAPI()

# This defines a "route" - a specific URL path
@app.get("/api/hello")
def read_root():
    # This returns a simple piece of data to the frontend
    return {"message": "Hello from FastAPI!"}

To run this, type uvicorn main:app --reload in your terminal. The --reload flag tells the server to restart every time you save a change.

Step 4: How do you connect the Frontend to the Backend?

Your frontend lives on one "port" (usually 3000) and your backend lives on another (usually 8000). To make them talk, you need to tell Next.js to send specific requests to Python.

Open the next.config.ts file in your main project folder. You will add a "rewrite" rule. This acts like a post office, redirecting any request starting with /api to your Python server.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        // This looks for any URL starting with /api
        source: '/api/:path*',
        // This sends it to your FastAPI server
        destination: 'http://127.0.0.1:8000/api/:path*',
      },
    ]
  },
};

export default nextConfig;

Step 5: How do you display data on the screen?

Now you can show the message from Python on your website. Open src/app/page.tsx and replace the code with this simple example:

'use client'; // This tells Next.js this page uses interactive features
import { useEffect, useState } from 'react';

export default function Home() {
  const [message, setMessage] = useState('Loading...');

  useEffect(() => {
    // This looks for the data from our Python backend
    fetch('/api/hello')
      .then((res) => res.json())
      .then((data) => setMessage(data.message));
  }, []);

  return (
    <main className="flex min-h-screen flex-col items-center justify-center">
      <h1 className="text-4xl font-bold">FastAPI + Next.js</h1>
      <p className="mt-4 text-xl">{message}</p>
    </main>
  );
}

When you save this file and look at your browser at http://localhost:3000, you should see "Hello from FastAPI!" on the screen. Don't worry if it takes a second to appear; the fetch command needs a moment to talk to the server.

What are the common Gotchas?

One frequent mistake is forgetting to activate the Python virtual environment. If you try to run uvicorn and get a "command not found" error, check that your terminal shows (venv) at the start of the line.

Another issue is the "CORS" (Cross-Origin Resource Sharing) error. This happens when a browser blocks a website from talking to a server for security reasons.

Using the rewrites method in next.config.ts usually solves this. It makes the browser think the frontend and backend are the same entity.

Finally, ensure both servers are running at the same time. You will need two terminal windows open: one running npm run dev and one running uvicorn.

Next steps

Now that you have the basic connection working, you can start building more complex features. You might want to try sending data from a form in Next.js to FastAPI to save it in a database.

You could also explore how to use Claude Sonnet 4 to generate text inside your FastAPI routes. This allows you to build AI features into your app very quickly.

It is normal to feel overwhelmed by having two different folders and languages. Just focus on one side at a time, and remember that the "API" is simply the bridge between them.

For more detailed guides, visit the official Next.Js documentation.

Read the Next.js Documentation