Build your first Aspire app

This quickstart uses the starter template that generates a C# AppHost. You’ll create the solution, review the generated AppHost, and run it locally with Aspire.

This starter template uses modern C#:

• Minimal APIs for lightweight HTTP APIs
• Blazor for interactive web UIs using C#
• Service defaults for shared configuration of observability and resilience

The following diagram shows the architecture of the sample app you’re creating:

architecture-beta

 service api(logos:dotnet)[API service]
 service frontend(aspire:blazor)[Blazor frontend]

 frontend:L --> R:api

This quickstart uses the JavaScript starter template, which generates a TypeScript AppHost in apphost.ts. You’ll create the solution, review the generated TypeScript AppHost, and run it locally with Aspire.

This starter template combines a modern JavaScript stack:

• Express for building APIs with Node.js
• React for building user interfaces with JavaScript
• TypeScript for type-safe development across the entire stack

The following diagram shows the architecture of the sample app you’re creating:

architecture-beta
 service api(logos:nodejs-icon)[API service]
 service frontend(logos:react)[React frontend]

 frontend:L --> R:api

To create your first Aspire application, use the Aspire CLI to generate a new solution from a template. These template include multiple projects, such as an API service, a web frontend, and an Aspire AppHost.

1. Create a new Aspire solution from a template:

   aspirenewaspire-starter-nAspireApp-oAspireApp

   The template provides several projects, including an API service, web frontend, and AppHost.

   For further CLI reference, see aspire new command information.

   If prompted for additional selections, use the and keys to navigate the options. Press to confirm your selection.

To create your first Aspire application, use the Aspire CLI to generate a new solution from a template. These template include multiple projects, such as an API service, a web frontend, and an Aspire AppHost.

1. Create a new Aspire solution from a template:

   aspirenewaspire-ts-starter-naspire-app-oaspire-app

   The template provides several projects, including an API service, web frontend, and AppHost.

   For further CLI reference, see aspire new command information.

   If prompted for additional selections, use the and keys to navigate the options. Press to confirm your selection.

1. Examine the created template structure. The Aspire CLI creates a new folder with the name you provided in the current directory. This folder contains the solution file and several projects, including:

   This solution structure is based on the Aspire templates. If they’re not installed already, the CLI will install them for you.

2. Explore the AppHost code that orchestrates your app.

   The AppHost is the heart of your Aspire application. It defines which services run, how they connect, and in what order they start. Let’s look at the generated code:

   var builder =DistributedApplication.CreateBuilder(args);
   var apiService =builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
   .WithHttpHealthCheck("/health");
   builder.AddProject<Projects.AspireApp_Web>("webfrontend")
   .WithExternalHttpEndpoints()
   .WithHttpHealthCheck("/health")
   .WithReference(apiService)
   .WaitFor(apiService);
   builder.Build().Run();

   What’s happening here?

   • CreateBuilder creates the distributed application builder
   • AddProject registers your API service and web frontend
   • WithReference connects services. It injects the API’s URL as an environment variable and sets up service discovery so you can use service names instead of hardcoded URLs
   • WaitFor ensures the API is healthy before starting the frontend, preventing connection errors from race conditions
   • WithHttpHealthCheck monitors service health

1. Examine the created template structure. The Aspire CLI creates a new folder with the name you provided in the current directory. This folder contains the solution file and several projects, including:

   This solution structure is based on the Aspire templates. If they’re not installed already, the CLI will install them for you.

2. Explore the AppHost code that orchestrates your app.

   The AppHost is the heart of your Aspire application. It defines which services run, how they connect, and in what order they start. Let’s look at the generated code:

   import{createBuilder}from'./.modules/aspire.js';
   constbuilder=awaitcreateBuilder();
   // Run the Express API and expose its HTTP endpoint externally.
   constapp=awaitbuilder
   .addNodeApp("app","./api","src/index.ts")
   .withHttpEndpoint({ env:"PORT"})
   .withExternalHttpEndpoints();
   // Run the Vite frontend after the API and inject the API URL for local proxying.
   constfrontend=awaitbuilder
   .addViteApp("frontend","./frontend")
   .withReference(app)
   .waitFor(app);
   // Bundle the frontend build output into the API container for publish/deploy.
   awaitapp.publishWithContainerFiles(frontend,"./static");
   awaitbuilder.build().run();

   What’s happening here?

   • createBuilder creates the distributed application builder
   • addNodeApp adds a Node.js application (the Express API)
   • addViteApp registers your React frontend
   • withReference connects the frontend to the API. It injects the API’s URL and sets up service discovery
   • waitFor ensures the API is running before starting the frontend, preventing connection errors
   • publishWithContainerFiles bundles the frontend for production deployment

   This template uses a TypeScript AppHost. To learn more about how multi-language AppHosts work, see Multi-language architecture.

1. Change to the output directory:

   cd./AspireApp

2. Call aspire run to start dev-time orchestration:

   aspirerun

   When you run this command, the Aspire CLI:

   • Automatically finds the AppHost
   • Builds your solution
   • Launches dev-time orchestration

   Once the dashboard is ready, its URL (with a login token highlighted in the example output below) appears in your terminal. The dashboard provides a live, real-time view of your running resources and their current states.

   🔍Findingapphosts...
   AspireApp.AppHost/AspireApp.AppHost.csproj
   🗄Createdsettingsfileat'aspire.config.json'.
   AppHost:AspireApp.AppHost/AspireApp.AppHost.csproj
   Dashboard:https://localhost:17068/login?t=ea559845d54cea66b837dc0ff33c3bd3
   Logs:%USERPROFILE%/.aspire/cli/logs/apphost-13024-2025-10-31-19-40-58.log
   PressCTRL+Ctostoptheapphostandexit.

   For further CLI reference, see aspire run command information.

3. Explore the running distributed application. From the dashboard, open the HTTPS endpoint from each resource.

   To learn more, see Aspire dashboard overview.

1. Change to the output directory:

   cd./aspire-app

2. Call aspire run to start dev-time orchestration:

   aspirerun

   When you run this command, the Aspire CLI:

   • Automatically finds the AppHost
   • Builds your solution
   • Launches dev-time orchestration

   Once the dashboard is ready, its URL (with a login token highlighted in the example output below) appears in your terminal. The dashboard provides a live, real-time view of your running resources and their current states.

   🔍Findingapphosts...
   apphost.ts
   AppHost:apphost.ts
   Dashboard:https://localhost:17174/login?t=afb274c630f48b1c4ddfe139011c1cb7
   Logs:%USERPROFILE%/.aspire/logs/cli_20260318T134627_f31ad598.log
   PressCTRL+Ctostoptheapphostandexit.

   For further CLI reference, see aspire run command information.

3. Explore the running distributed application. From the dashboard, open the HTTPS endpoint from each resource.

   To learn more, see Aspire dashboard overview.

1. Stop the AppHost and close the dashboard by pressing in your terminal.

   🛑StoppingAspire.

   🥳 Congratulations! You’ve created your first Aspire app.

1. Stop the AppHost and close the dashboard by pressing in your terminal.

   🛑StoppingAspire.

   🥳 Congratulations! You’ve created your first Aspire app.