⚛ React + ASP.NET Core Guide

3. Solution anatomy

Two projects, one solution. Understanding how they connect makes everything else easier.

Typical layout

ReactWithAspNet/
  ReactWithAspNet.sln
  reactwithaspnet.client/            React app (.esproj)
    reactwithaspnet.client.esproj
    package.json
    vite.config.js
    index.html
    public/
    src/
      main.jsx
      App.jsx
      App.css
  ReactWithAspNet.Server/            ASP.NET Core API
    ReactWithAspNet.Server.csproj
    Program.cs
    Controllers/
    Properties/launchSettings.json

The client project (.esproj)

The .esproj uses the JavaScript project SDK. It lets Visual Studio treat the React app as a first-class project: npm node, build integration, Test Explorer support and an editing experience for JavaScript or TypeScript.

<Project Sdk="Microsoft.VisualStudio.JavaScript.Sdk/VERSION">
  <PropertyGroup>
    <StartupCommand>npm run dev</StartupCommand>
    <ShouldRunBuildScript>false</ShouldRunBuildScript>
    <BuildOutputFolder>$(MSBuildProjectDirectory)\dist</BuildOutputFolder>
  </PropertyGroup>
</Project>

The server project (.csproj)

The server references the client project so that building or publishing the server also builds the React app, but it takes no assembly from it:

<ItemGroup>
  <ProjectReference Include="..\reactwithaspnet.client\reactwithaspnet.client.esproj">
    <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
  </ProjectReference>
</ItemGroup>

Depending on the template version, the server may also include SPA proxy settings that launch the Vite dev server when you run the server project (for example SpaRoot, SpaProxyLaunchCommand and SpaProxyServerUrl).

vite.config.js: the dev proxy

In development the browser talks to the Vite dev server (hot reload). Vite forwards API calls to ASP.NET Core:

import { fileURLToPath, URL } from 'node:url';
import { defineConfig } from 'vite';
import plugin from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [plugin()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  server: {
    proxy: {
      '^/api': {
        target: 'https://localhost:7183',   // must match the server's https applicationUrl
        secure: false
      }
    },
    port: 5173
  }
});
The proxy target port must match the server project's HTTPS applicationUrl in launchSettings.json. A mismatch is the most common cause of "proxy error" messages.

Program.cs: serving the built React app

In production there is no Vite. ASP.NET Core serves the compiled files from wwwroot and falls back to index.html for client-side routes:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseDefaultFiles();
app.MapStaticAssets();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.UseAuthorization();

app.MapControllers();
app.MapFallbackToFile("/index.html");

app.Run();

How a request flows

ModeBrowser loads the page fromAPI calls go to
DevelopmentVite dev server (e.g. https://localhost:5173)Vite, which proxies /api/* to ASP.NET Core
ProductionASP.NET Core (static files in wwwroot)The same ASP.NET Core app, same origin, so no CORS needed