.NET Aspire & Next.js: The Dev Experience You Were Missing

Streamline Local Development with .NET Aspire

Next.js has been the modern web developments golden standard for years, and with the recent release of React 19, that momentum isn’t slowing down. But if you’ve ever tried running a Next.js frontend alongside a .NET API in local development, you already know the pain:

• Managing Dockerfiles and docker-compose just to get a basic setup working
• Fighting hot-reloading issues with .NET inside Docker
• Constantly tweaking volume mounts and dotnet watch run hoping for a smooth experience

Let’s be real—traditional containerized development sucks for quick iteration. Enter .NET Aspire, Microsoft’s local development orchestration tool. With Aspire, you get:

• Seamless orchestration - No need for deviating Dockerfiles for local development
• Built-in service discovery
• Support for hot-reloading - Changes in your API reflect instantly, no container restarts required
• Sane local development - Run everything together without the usual containerization headaches

Honestly, setting up Aspire is so easy, I now add it to all my new projects. Even if I don’t need it right away, I know it’ll save me time down the line.

Setting Up .NET Aspire for API and Frontend Development

Let’s get the boilerplate out of the way. We need a solution that includes a .NET Aspire Host and ServiceDefaults, a .NET API, and a Next.js website. You can run the following commands to set up a basic project.

Running a .NET API with Aspire is pretty easy, for an API without any dependencies we can simply add this line to our DotnetAspireNext.AppHost/Program.cs:

Adding Next.js to .NET Aspire

Aspire allows us to orchestrate Node.js apps using the Aspire.Hosting.NodeJS package. This package provides two ways to integrate Node projects: AddNodeApp and AddNpmApp. Even though Next.js is technically a Node app, we need to use AddNpmApp because Next.js apps run with npm run dev instead of node somefile.js.

If you prefer using Yarn or PNPM, you can use CommunityToolkit.Aspire.Hosting.NodeJS.Extensions.

_10

dotnet add DotnetAspireNext.AppHost package Aspire.Hosting.NodeJS

_10

# or when using Yarn or PNPM

_10

dotnet add DotnetAspireNext.AppHost package CommunityToolkit.Aspire.Hosting.NodeJS.Extensions

Why you might still want to use the CommunityToolkit extensions

Now we can configure Aspire to run our Next.js project like so:

_10

var api = builder.AddProject<DotnetAspireNext_Api>("api");

_10

_10

var frontend = builder

_10

.AddNpmApp("frontend", "../frontend", "dev")

_10

.WithNpmPackageInstallation()

_10

.WaitFor(api)

_10

.WithReference(api)

_10

.WithHttpEndpoint(env: "PORT") // Make sure Next.js uses the port assigned by Aspire

_10

.WithExternalHttpEndpoints();

Running the Aspire project will quickly show us that both our API and Next app are running and accessible:

Fetching Data from Your .NET API in Next.js

There are several ways to access our API from our Next.js project.

The simplest approach is to export a variable containing the API endpoint or create a fetch/axios wrapper with the endpoint hardcoded. However, you’d then need a way to update this value when deploying to a server.

A better approach is to use environment variables. Fortunately, Aspire automatically adds an environment variable to our frontend project when we include .WithReference(api). If we check the Aspire Dashboard, we can see an environment variable called services__api__http__0 containing the API endpoint.

Accessing .NET Aspire Service Endpoints Dynamically

Aspire works some magic behind the scenes to ensure each service has a single predictable endpoint, regardless of how many replicas or services are running.

This 'magic' boils down to Aspire placing proxies before each service you register. It is the proxy that listens on the port defined in launchSettings.json or .WithEndpoint(). Meanwhile, the actual app runs on a different endpoint managed by Aspire. This allows multiple instances of an application to run while keeping a single predictable endpoint.

While this setup is useful, it can cause issues if an application assumes its internal address matches its external address.

Endpoints are assigned after calling builder.Build().Run();. However, .WithEnvironment() has an overload that accepts a callback, which runs after Aspire assigns all endpoints. This allows us to use GetEndpoint() on a service resource to set environment variables dynamically. Normally, calling GetEndpoint() too early would throw an exception since the endpoint wouldn’t exist until the Aspire stack is built.

Wrapping Up

.NET Aspire makes it surprisingly easy to orchestrate a local development environment. Instead of dealing with complex Docker setups or unreliable hot-reloading, you get a streamlined workflow where everything just works.

If you're already working with .NET, this setup is worth exploring. It makes local development a lot more enjoyable and efficient. Adding additional dependencies, like Redis or PostgreSQL, is just as easy as adding a new project.

Of course, no tool is perfect. .NET Aspire is still evolving, and depending on your project’s needs, you may run into edge cases. But if you’re looking for a cleaner, more efficient way to develop locally, this approach is certainly worth trying.

I’ll be diving deeper into .NET Aspire in future articles—covering more advanced scenarios, potential pitfalls, and how it fits into real-world workflows. So if you're experimenting with it yourself, keep an eye out for what’s next.