Add recipe for passing Aspire parameters to SPA frontends (Vite/React runtime config)

[maddymontaquila]

Type of issue

Missing information / new recipe needed

Description

When using AddViteApp with Aspire parameters (e.g., Google OAuth Client ID), there's no documented pattern for getting parameter values into the SPA at runtime.

The problem: Vite bakes VITE_* environment variables into the JavaScript bundle at build time. Aspire sets environment variables at runtime. This means .WithEnvironment("VITE_GOOGLE_CLIENT_ID", parameter) on a Vite resource doesn't work — the value isn't available when Vite compiles the frontend.

What we had to figure out ourselves:

1. Pass the parameter to the API project as a regular env var: .WithEnvironment("GOOGLE_CLIENT_ID", googleClientId)
2. Create a config endpoint in the API: GET /api/config/google-client-id
3. Have the SPA fetch the config value at mount time instead of reading import.meta.env

This is a universal problem for anyone using AddViteApp / AddNpmApp with parameters. A recipe or guide would save a lot of confusion.

Suggested docs location: The JavaScript hosting docs or the external parameters page would be natural homes.

Alternatively: A first-class API like AddViteApp(...).WithFrontendConfig("GOOGLE_CLIENT_ID", parameter) that auto-generates the config endpoint would be even better (that would be a dotnet/aspire feature request).

Page URL

https://learn.microsoft.com/en-us/dotnet/aspire/get-started/build-aspire-apps-with-nodejs

Content source URL

https://github.com/microsoft/aspire.dev/blob/main/docs/get-started/build-aspire-apps-with-nodejs.md

[maddymontaquila]

Bumping this with a concrete workaround we've been using successfully for two sprints.

Working pattern: Config endpoint bridge

Since Vite bakes VITE_* env vars at build time and Aspire sets env vars at runtime, we bridge the gap with a simple API endpoint.

1. AppHost — pass the parameter to the API as an env var

var googleClientId = builder.AddParameter("google-client-id");

var api = builder.AddProject("api", "./src/api")
    .WithEnvironment("GOOGLE_CLIENT_ID", googleClientId);

builder.AddViteApp("frontend", "./src/frontend")
    .WithPnpm()
    .WithReference(api);

2. API project — expose a config endpoint

// ConfigEndpoints.cs
public static class ConfigEndpoints
{
    public static void MapConfigEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/config");

        group.MapGet("/google-client-id", (IConfiguration config) =>
        {
            var clientId = config["GOOGLE_CLIENT_ID"];
            if (string.IsNullOrEmpty(clientId))
                return Results.NotFound("Google Client ID not configured");

            return Results.Ok(new { clientId });
        });
    }
}

3. SPA frontend — fetch at mount time

const response = await fetch('/api/config/google-client-id');
const { clientId } = await response.json();

This has been stable across two sprints. It's straightforward but every Vite+Aspire project will need to reinvent it — a docs recipe would save teams significant time.

We've also filed dotnet/aspire#14471 as a feature request for a first-class WithFrontendConfig API that could eliminate this boilerplate entirely.