Build your first Aspire app

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

Prerequisites

Prefer VS Code?

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 youre 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.mts. Youll create the solution, review the generated TypeScript AppHost, and run it locally with Aspire.

Prerequisites

Prefer VS Code?

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 youre 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:

   Create a new aspire solution

   aspire new aspire-starter -n AspireApp -o AspireApp

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

   CLI flags

   The following flags are used in the command:

   • -n: specifies the name of the solution.
   • -o: specifies the output directory.

   For further CLI reference, see aspire new command information.

   If prompted for additional selections, use the Up ArrowUp ArrowUp Arrow and Down ArrowDown ArrowDown Arrow keys to navigate the options. Press ReturnReturnEnterEnterEnterEnter 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:

   Create a new aspire solution

   aspire new aspire-ts-starter -n aspire-app -o aspire-app

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

   CLI flags

   The following flags are used in the command:

   • -n: specifies the name of the solution.
   • -o: specifies the output directory.

   For further CLI reference, see aspire new command information.

   If prompted for additional selections, use the Up ArrowUp ArrowUp Arrow and Down ArrowDown ArrowDown Arrow keys to navigate the options. Press ReturnReturnEnterEnterEnterEnter to confirm your selection.

   AI agent environments

   When prompted Would you like to configure AI agent environments for this project?, select y. This sets up workspace configurations (such as Aspire skills and MCP server settings) for your project, enabling a richer experience with AI coding assistants. For more information, see Use AI coding agents and the aspire agent init reference.

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:

   • AspireApp.sln
   • DirectoryAspireApp.ApiService mock weather data API
     • DirectoryProperties/
     • appsettings.Development.json
     • appsettings.json
     • AspireApp.ApiService.csproj
     • Program.cs
   • DirectoryAspireApp.AppHost dev-time orchestrator
     • DirectoryProperties/
     • appsettings.Development.json
     • appsettings.json
     • AspireApp.AppHost.csproj
     • AppHost.cs
   • DirectoryAspireApp.ServiceDefaults
     • Extensions.cs
     • AspireApp.ServiceDefaults.csproj
   • DirectoryAspireApp.Web ASP.NET Core Blazor frontend
     • DirectoryProperties/
     • Directorywwwroot/
     • appsettings.Development.json
     • appsettings.json
     • AspireApp.Web.csproj
     • Program.cs
     • WeatherApiClient.cs

   This solution structure is based on the Aspire templates. If theyre 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. Lets look at the generated code:

   AppHost.cs project-based orchestrator

   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();

   Whats happening here?

   • CreateBuilder creates the distributed application builder
   • AddProject registers your API service and web frontend
   • WithReference connects services. It injects the APIs 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

   Code-first orchestration

   Your application topology is defined in code, making it easy to understand, modify, and version control. Learn more about the AppHost.

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:

   • Directoryaspire-app/
     • Directoryapi/ Express mock weather data API
       • Directorysrc/
         • index.ts
         • instrumentation.ts
       • package.json
       • tsconfig.json
     • Directoryfrontend/ Vite + React web frontend
       • Directorypublic/
         • Aspire.png
         • github.svg
       • Directorysrc/
         • App.css
         • App.tsx
         • index.css
         • main.tsx
         • vite-env.d.ts
       • .dockerignore
       • eslint.config.js
       • index.html
       • package.json
       • tsconfig.json
       • vite.config.ts
     • apphost.mts dev-time orchestrator
     • Directory.aspire/
       • Directorymodules/ generated TypeScript SDK
     • aspire.config.json
     • package.json
     • tsconfig.apphost.json

   This solution structure is based on the Aspire templates. If theyre 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. Lets look at the generated code:

   apphost.mts

   import { 
   function createBuilder(): IDistributedApplicationBuilder
   Creates a new distributed application builder
   createBuilder } from './.aspire/modules/aspire.mjs';
   
   const 
   const builder: IDistributedApplicationBuilder
   builder = await 
   function createBuilder(): IDistributedApplicationBuilder
   Creates a new distributed application builder
   createBuilder();
   
   // Run the Express API and expose its HTTP endpoint externally.
   const 
   const app: NodeAppResource
   app = await 
   const builder: IDistributedApplicationBuilder
   builder
       .
   IDistributedApplicationBuilder.addNodeApp(name: string, appDirectory: string, scriptPath: string): NodeAppResource
   Adds a node application to the application model. Node should be available on the PATH.
   addNodeApp("app", "./api", "src/index.ts")
       .
   ExecutableResource.withHttpEndpoint(options?: {
       port?: number;
       targetPort?: number;
       name?: string;
       env?: string;
       isProxied?: boolean;
   } | undefined): NodeAppResource (+1 overload)
   Adds an HTTP endpoint
   withHttpEndpoint({ 
   env?: string | undefined
   env: "PORT" })
       .
   ExecutableResource.withExternalHttpEndpoints(): NodeAppResource
   Marks existing http or https endpoints on a resource as external.
   withExternalHttpEndpoints();
   
   // Run the Vite frontend after the API and inject the API URL for local proxying.
   const 
   const frontend: ViteAppResource
   frontend = await 
   const builder: IDistributedApplicationBuilder
   builder
       .
   IDistributedApplicationBuilder.addViteApp(name: string, appDirectory: string, options?: {
       runScriptName?: string;
   }): ViteAppResource (+1 overload)
   Adds a Vite app to the distributed application builder.
   addViteApp("frontend", "./frontend")
       .
   ExecutableResource.withReference(source: EndpointReference | string | uri, options?: {
       connectionName?: string;
       optional?: boolean;
       name?: string;
   } | undefined): ViteAppResource (+1 overload)
   Adds a reference to another resource
   withReference(
   const app: NodeAppResource
   app)
       .
   ExecutableResource.waitFor(dependency: IResource | IResourceWithConnectionString, waitBehavior?: WaitBehavior): ViteAppResource
   Waits for another resource to be ready
   waitFor(
   const app: NodeAppResource
   app);
   
   // Bundle the frontend build output into the API container for publish/deploy.
   await 
   const app: NodeAppResource
   app.
   IContainerFilesDestinationResource.publishWithContainerFiles(source: IResourceWithContainerFiles, destinationPath: string): NodeAppResource
   Configures the resource to copy container files from the specified source resource during publishing.
   publishWithContainerFiles(
   const frontend: ViteAppResource
   frontend, "./static");
   
   await 
   const builder: IDistributedApplicationBuilder
   builder.
   IDistributedApplicationBuilder.build(): DistributedApplication
   Builds the distributed application
   build().
   DistributedApplication.run(cancellationToken?: cancellationToken): void
   Runs the distributed application
   run();

   Whats 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 APIs 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.

   Code-first orchestration

   Your application topology is defined in code, making it easy to understand, modify, and version control. Learn more about the AppHost.

1. Change to the output directory:

   Change directories

   cd ./AspireApp

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

   Run dev-time orchestration

   aspire run

   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.

   Example output

     Finding apphosts...
   AspireApp.AppHost/AspireApp.AppHost.csproj
   
     Created settings file at '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
   
                  Press CTRL+C to stop the apphost and exit.

   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.

   [Aspire dashboard Resources page displaying two running resources: apiservice and webfrontend. Both are marked as Running with green check icons. The table lists columns for Name, State, Start time, Source, URLs, and Actions.]

   To learn more, see Aspire dashboard overview.

1. Change to the output directory:

   Change directories

   cd ./aspire-app

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

   Run dev-time orchestration

   aspire run

   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.

   Example output

     Finding apphosts...
   apphost.mts
   
        AppHost:  apphost.mts
   
      Dashboard:  https://localhost:17174/login?t=afb274c630f48b1c4ddfe139011c1cb7
   
           Logs:  %USERPROFILE%/.aspire/logs/cli_20260318T134627_f31ad598.log
   
                  Press CTRL+C to stop the apphost and exit.

   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.

   [Aspire dashboard Resources page displaying two running and two finished resources: app and frontend. Both app and frontend are marked as Running with green check icons while their installer resources show as Finished. The table lists columns for Name, State, Start time, Source, URLs, and Actions.]

   To learn more, see Aspire dashboard overview.

1. Stop the AppHost and close the dashboard by pressing +C+CControl + CCtrlCControl + CCtrlC in your terminal.

   Stop dev-time orchestration

     Stopping Aspire.

   Congratulations! Youve created your first Aspire app.

1. Stop the AppHost and close the dashboard by pressing +C+CControl + CCtrlCControl + CCtrlC in your terminal.

   Stop dev-time orchestration

     Stopping Aspire.

   Congratulations! Youve created your first Aspire app.