Make Aspire better for client-side JavaScript developers.

[mitchdenny]

The Aspire team wants to make Aspire more friendly to client-side JavaScript developers. Today we have APIs such as AddNpmApp(...) and AddNodeApp(...). These are fairly thin wrappers around adding an executable.

What we would like to do is add an API which is more squarely targetted at the client-side developer. Let's walk through what we are thinking by looking at some code:

builder.AddClientsideJavaScriptApp("frontend")
       .WithHttpEndpoint(env: "PORT")
       .WithRestoreCommand("npm install")
       .WithRunCommand("npm run dev")
       .WithPublishCommand("npm run build", outputPath: "dist")
       .WithHttpOtelCollector()
       .WithEnvironmentPrefix("OTEL_", "VITE_OTEL_")
       .WithEnvironment("BACKEND", api)
       .WithReference(api, env: "BACKEND")
       .WithReference(api, endpointName: "http", env: "BACKEND")
       .PublishAsDockerfile()
       .PublishAsNginx()
       .PublishAsCaddyserver()
       .PublishAsAzureBlobStorage(...);

Lets look at each of these lines in a bit more detail:

builder.AddClientsideJavaScriptApp("frontend")
       .WithRestoreCommand("npm install")
       .WithRunCommand("npm run dev")
       .WithPublishCommand("npm run build", outputPath: "dist")

This would be a new resource (ClientsideJavaScriptResource) which derives from executable resource (so similar to Node/NPM resources in that respect). Its type would enable the use of the WithRunCommand(...), WithRestoreComand(...), and WithPublishCommand(...). This methods might hang off a common interface that we could use across different language ecosystems. For example we could do something similar with Python.

The effect of these methods in the dashboard is that the client-side JS resource would show the log output from invoking npm run dev. But there would be a child resource for the restore command. The parent resource would actually have a WaitForCompletion(...) on its child resource.

The publish command data would be stored in an annotation which is used by the code that publishes the app in the appropriate way (probably by creating a container image).

WithHttpOtelCollector(...)

.WithHttpOtelCollector(...)

This would add an annotation on the resource that signals that when the dashboard launches it should expose not just gRPC, but also the http collector (we'll need to do work to support that in the dashboard - /cc @JamesNK). Its likely that the AddClientsideJavaScriptApp(...) implicitly calls this method, its shown here so we could discuss the need for it.

Environment variable prefixes

Many JavaScript tools use a prefixing mechanism to control a set of variables which are injected into the client-side code. For example Vite has a VITE_ prefix. We will add a method that allows us to find existing variables on the resource and remap them.

       .WithEnvironmentPrefix("OTEL_", "VITE_OTEL_")

This will probably need to be a specialized annotation that DCP supports so that it is always processed after all other environment variables have been generated.

Service discovery environment variables

We are having some debate on whether we should just get folks to use WithEnvironment("name", resource) - or whether we make some extensions to WithReference(...). There is a possibility of an NPM package which does service discovery integration. There will probably be a crawl-walk-run story here.

Publishing extensions

We want to make it easy to bundle up the client side JavaScript on a web server for deployment. We could have the following options:

       .PublishAsDockerfile() // roll your own
       .PublishAsNginx()
       .PublishAsCaddyserver()
       .PublishAsYarp()
       .PublishAsAzureBlobStorage(...); // static CDN hosting scenarios

More detail to follow.

[mitchdenny]

/cc @davidfowl @maddymontaquila @glennc @DamianEdwards @robrich

[robrich]

When we add .WithHttpOtelCollector() (implicitly in the .AddBrowserJavaScriptApp()) it not only needs to turn on the HTTP OTEL collector in the Aspire dashboard ("DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "http...), it also needs to send the env vars that use the HTTP protocol because browsers can't send gRPC.

[CZEMacLeod]

@robrich I have a similar issue with net48 where the open telemetry client cannot support SSL certificates in GRPC mode but it can in HTTP mode. This means that we need to disable the DOTNET_DASHBOARD_OTLP_ENDPOINT_URL variable in the aspire host launch profile. If we could pass an option to WithOtlpExporter that could specify which endpoint to use per resource it would be very helpful.

aspire/src/Aspire.Hosting/OtlpConfigurationExtensions.cs

Lines 46 to 61 in 84d6e25

	// The dashboard can support OTLP/gRPC and OTLP/HTTP endpoints at the same time, but it can
	// only tell resources about one of the endpoints via environment variables.
	// If both OTLP/gRPC and OTLP/HTTP are available then prefer gRPC.
	if (dashboardOtlpGrpcUrl != null)
	{
	SetOtelEndpointAndProtocol(context.EnvironmentVariables, dashboardOtlpGrpcUrl, "grpc");
	}
	else if (dashboardOtlpHttpUrl != null)
	{
	SetOtelEndpointAndProtocol(context.EnvironmentVariables, dashboardOtlpHttpUrl, "http/protobuf");
	}
	else
	{
	// No endpoints provided to host. Use default value for URL.
	SetOtelEndpointAndProtocol(context.EnvironmentVariables, DashboardOtlpUrlDefaultValue, "grpc");
	}

This would be a real help.

[aaronpowell]

I've got a few thoughts on this from having built some extensions in the Community Toolkit for the Node.js hosting package.

First one, I think it should be AddClient**S**ideJavaScriptApp not AddClient**s**ideJavaScriptApp - I tackle the important stuff first 😜.

Regarding the API:

       .WithRunCommand("npm run dev")
       .WithPublishCommand("npm run build", outputPath: "dist")

I don't really love this, as it feels like it's breaking from the standard design of Aspire and requiring you to make the client side app really special, rather than having it on the initial resource registration. For example, what if I don't include the WithRunCommand, what does it do? and is the run command only valid for dev but not in production? what about WithPublishCommand if I'm using PublishAsDockerfile, aren't I doing two publish steps?

       .WithEnvironmentPrefix("OTEL_", "VITE_OTEL_")
       .WithEnvironment("BACKEND", api)
       .WithReference(api, env: "BACKEND")
       .WithReference(api, endpointName: "http", env: "BACKEND")

These are great additions as the way environment variables are surfaced to apps currently is very foreign to a JS developer and as a result you either have to write a bunch of mapping code yourself or just accept that you're mixing ideas.

.WithRestoreCommand("npm install")

With the extensions package in the Community Toolkit we've essentially implemented this via the WithNpmPackageInstallation (and yarn + pnpm versions) method. While I think I understand the intent of your API proposal - allow the arbitrary command to be provided so there's flexibility in what it does (maybe run a "cleanup" script first), I think what it's doing is devaluing the role of npm run-script and the workflow that is common place in JavaScript apps. If there is "other stuff" to be done to complete an npm install, such as running pre/post scripts, then we do that with a preinstall/postinstall script definition.

[KLuuKer]

We use yarn instead of npm (just incase anybody was planning to hardcoding everything to use npm "again")

p.s. pnpm and bun & deno also exist, and the last 2 apparently have their own node.js runtime alternative (not sure if there needs to be a runtime flexibility but just to keep in mind alternatives exists)

[KLuuKer]

Just because i want to run webpack --watch during development doesn't not mean i want that always...
When deploying to production maybe i just want to publish files to disk instead.
Maybe someone else publishes a whole container that gets an ingress attached to it.

[anfibiacreativa]

We use yarn instead of npm (just incase anybody was planning to hardcoding everything to use npm "again")

p.s. pnpm and bun & deno also exist, and the last 2 apparently have their own node.js runtime alternative (not sure if there needs to be a runtime flexibility but just to keep in mind alternatives exists)

This is a very valid concern that I have already expressed with previous feedback.
The JavaScript ecosystem is specially open and dynamic.

I am going to go further with the important stuff Aaron pointed at :P, and ask,...what about SSR apps? Maybe just call it AddFrontendApp (What if it's TS?). It may feel trivial but for those who work with these technologies, it may be confusing about constraints, limitations and even architecture decisions and references.