Aspire.Hosting.NodeJs<\/code>, because we renamed it to be less confusing\u2014you’re welcome) brings comprehensive support for developing, debugging, and deploying JavaScript applications. Whether you’re building slick frontends with Vite, REST APIs with Express, or full-stack apps with Next.js, Aspire’s got your back.<\/p>\n\ud83d\ude80 Adding JavaScript applications to Aspire<\/h2>\n
Aspire 13 gives you three different ways to run JavaScript code, each tailored for specific scenarios. Think of them as different tools in your toolbox\u2014you wouldn’t use a sledgehammer to hang a picture frame, right? (Well, you could, but results may vary \ud83e\udd23!)<\/p>\n
\ud83d\udce6 JavaScript applications: The npm script runner<\/h3>\n
Got a package.json<\/code> with scripts? AddJavaScriptApp()<\/code> is your new best friend. It’s perfect for literally any JavaScript project that uses npm scripts\u2014React, Angular, Vue, Express, Next.js, that weird side project you started at 2 AM, you name it.<\/p>\nvar builder = DistributedApplication.CreateBuilder(args);\n\nvar frontend = builder.AddJavaScriptApp(\"frontend\", \"..\/frontend\");\n\nbuilder.Build().Run();<\/code><\/pre>\nDead simple. By default, it runs your \"dev\"<\/code> script during local development and your \"build\"<\/code> script when you’re deploying. No fuss, no ceremony, just works.<\/p>\n\ud83d\udce5 Package manager support: Because one size doesn’t fit all<\/h4>\n
Look, I know the JavaScript ecosystem has opinions, lots of them, I get it…but Aspire supports them already. If your project has a package.json<\/code>, npm is auto-configured as the default. But if you’re team Yarn or team pnpm (respect), switching is trivial:<\/p>\n\/\/ npm (default) with custom arguments\nvar app = builder.AddJavaScriptApp(\"app\", \"..\/app\")\n .WithNpm(installArgs: [\"--legacy-peer-deps\"]);\n\n\/\/ Yarn\nvar yarnApp = builder.AddJavaScriptApp(\"yarn-app\", \"..\/yarn-app\")\n .WithYarn();\n\n\/\/ pnpm\nvar pnpmApp = builder.AddJavaScriptApp(\"pnpm-app\", \"..\/pnpm-app\")\n .WithPnpm();\n\n\/\/ Disable automatic installation (for pre-installed dependencies)\nvar noInstallApp = builder.AddJavaScriptApp(\"no-install\", \"..\/no-install\")\n .WithNpm(install: false);<\/code><\/pre>\nHere’s what’s happening under the hood (because details matter):<\/p>\n
npm’s got smarts:<\/strong><\/p>\n\n- Development: Uses
npm install<\/code> (the classic)<\/li>\n- Production: Automatically switches to
npm ci<\/code> if it spots a package-lock.json<\/code> (faster, more reliable, chef’s kiss)<\/li>\n<\/ul>\nYarn plays nice:<\/strong><\/p>\n\n- Auto-detects your Yarn version by checking for
.yarnrc.yml<\/code> or the .yarn<\/code> directory<\/li>\n- Yarn 2+: Uses
yarn install --immutable<\/code> in production when yarn.lock<\/code> exists (no surprises)<\/li>\n- Yarn 1.x: Uses
yarn install --frozen-lockfile<\/code> in production (because legacy support matters)<\/li>\n<\/ul>\npnpm just works:<\/strong><\/p>\n\n- Uses
pnpm install --frozen-lockfile<\/code> in production when pnpm-lock.yaml<\/code> exists<\/li>\n- Automatically enables pnpm via corepack in Docker builds (we’re not savages)<\/li>\n<\/ul>\n
<\/i>Note<\/strong><\/p> The install<\/code> parameter (default: true<\/code>) controls whether packages are automatically installed before the application starts. Set to false<\/code> to skip installation when dependencies are already in place. <\/div><\/p>\n\ud83d\udd27 Script customization: Your package.json, your rules<\/h4>\n
Don’t like the default \"dev\"<\/code> and \"build\"<\/code> scripts? No problem. Override them:<\/p>\nvar app = builder.AddJavaScriptApp(\"app\", \"..\/app\")\n .WithRunScript(\"local\") \/\/ Use \"npm run local\" in development\n .WithBuildScript(\"build:prod\"); \/\/ Use \"npm run build:prod\" when publishing<\/code><\/pre>\nNeed to pass arguments? We got you:<\/p>\n
var app = builder.AddJavaScriptApp(\"app\", \"..\/app\")\n .WithRunScript(\"dev\", [\"--port\", \"3000\", \"--host\"]);<\/code><\/pre>\n\u2699\ufe0f Node.js applications: Direct execution, no package manager required<\/h3>\n
Sometimes you just want to run node server.js<\/code> and call it a day. No npm scripts, no build steps, just pure Node.js execution. That’s where AddNodeApp()<\/code> shines:<\/p>\nvar nodeApp = builder.AddNodeApp(\"node-app\", \"..\/node-app\", \"server.js\")\n .WithHttpEndpoint(env: \"PORT\");<\/code><\/pre>\nPerfect for simple Node.js scripts, microservices, background workers, or when you want direct control over the Node.js process without the npm script ceremony. (Sometimes less is more, you know?)<\/p>\n
\ud83d\udce5 Adding dependencies to Node apps<\/h4>\n
Your Node app has dependencies? Of course it does. When there’s a package.json<\/code>, npm kicks in automatically. You can mix and match package managers with npm scripts if that’s your jam:<\/p>\n\/\/ Use Yarn with npm scripts\nvar nodeApp = builder.AddNodeApp(\"node-app\", \"..\/node-app\", \"server.js\")\n .WithYarn()\n .WithRunScript(\"dev\"); \/\/ Now uses \"yarn run dev\" instead of \"node server.js\"\n\n\/\/ Use pnpm\nvar pnpmNode = builder.AddNodeApp(\"pnpm-node\", \"..\/pnpm-node\", \"server.js\")\n .WithPnpm();<\/code><\/pre>\n\ud83d\ude80 What happens in production<\/h4>\n
When you publish AddNodeApp()<\/code>, Aspire generates multi-stage Dockerfiles that are actually good (I know, shocking). Here’s what you get:<\/p>\n\n- Build stage<\/strong> installs dependencies and runs your build scripts<\/li>\n
- Runtime stage<\/strong> copies only the built artifacts (smaller images, faster deploys, happier DevOps team)<\/li>\n
- Runs as the non-privileged
node<\/code> user (because security isn’t optional)<\/li>\n- Sets proper entrypoint as
[\"node\", \"your-script.js\"]<\/code> (no weird shell wrapping nonsense)<\/li>\n<\/ul>\n\u26a1 Vite applications: Frontend frameworks, but faster<\/h3>\n
If you’re building modern frontends with Vite (and you should be\u2014it’s ridiculously fast), use AddViteApp()<\/code> for Vite-specific optimizations:<\/p>\nvar viteApp = builder.AddViteApp(\"vite-app\", \"..\/vite-app\");<\/code><\/pre>\nWorks beautifully with React, Vue, Svelte, Astro, or any Vite-based framework.<\/p>\n
\u2699\ufe0f What Aspire does for you automatically<\/h4>\n
AddViteApp()<\/code> is kind of magical. Behind the scenes, it:<\/p>\n\n- Configures an HTTP endpoint (port gets allocated dynamically\u2014no more port conflicts!)<\/li>\n
- Passes the
--port<\/code> argument to Vite with the allocated port<\/li>\n- Runs the “dev” script during development<\/li>\n
- Runs the “build” script when publishing<\/li>\n
- Handles the
--<\/code> separator correctly for pnpm (because pnpm is special and doesn’t strip it like npm\/Yarn do)<\/li>\n- Generates production-ready Dockerfiles<\/li>\n<\/ul>\n
All of this, without you lifting a finger. It’s almost too easy.<\/p>\n
\ud83d\udce5 Package managers for Vite apps<\/h4>\n
Like AddJavaScriptApp()<\/code>, Vite apps support all the package managers you’d expect:<\/p>\n\/\/ npm (default)\nvar viteApp = builder.AddViteApp(\"vite-app\", \"..\/vite-app\");\n\n\/\/ Yarn\nvar yarnVite = builder.AddViteApp(\"yarn-vite\", \"..\/yarn-vite\")\n .WithYarn();\n\n\/\/ pnpm\nvar pnpmVite = builder.AddViteApp(\"pnpm-vite\", \"..\/pnpm-vite\")\n .WithPnpm();<\/code><\/pre>\n\ud83d\udcc4 Custom Vite configs: For when defaults aren’t enough<\/h4>\n
Got multiple Vite configs for different environments? (Of course you do.) Point Aspire at the right one:<\/p>\n
var viteApp = builder.AddViteApp(\"vite-app\", \"..\/vite-app\")\n .WithViteConfig(\".\/vite.production.config.js\");<\/code><\/pre>\nThe path is relative to your Vite app’s root directory. Pretty straightforward stuff.<\/p>\n
\ud83d\udd12 HTTPS configuration: Certificate trust without the trust issues<\/h4>\n
Here’s where things get clever. Aspire handles HTTPS for Vite without butchering your carefully crafted vite.config.js<\/code>. When you configure HTTPS certificates, Aspire generates a wrapper<\/em> config that layers HTTPS settings on top:<\/p>\nvar viteApp = builder.AddViteApp(\"vite-app\", \"..\/vite-app\")\n .WithHttpsEndpoint(env: \"PORT\")\n .WithHttpsDeveloperCertificate();<\/code><\/pre>\nWhat happens under the hood:<\/p>\n
\n- Aspire finds your existing Vite config (or uses Vite’s default resolution)<\/li>\n
- Generates a wrapper config at
node_modules\/.bin\/aspire.{your-config}.js<\/code><\/li>\n- Passes cert paths through
TLS_CONFIG_PFX<\/code> and TLS_CONFIG_PASSWORD<\/code> environment variables<\/li>\n- Augments your config to use HTTPS if it’s not already set up<\/li>\n<\/ol>\n
Your original vite.config.js<\/code>? Untouched. Beautiful. This is how you do non-invasive tooling.<\/p>\n<\/i>Important<\/strong><\/p> Vite apps use HTTP by default. HTTPS is opt-in via WithHttpsEndpoint()<\/code> and requires calling WithHttpsDeveloperCertificate()<\/code> or providing a custom certificate. <\/div><\/p>\n\ud83c\udf10 Endpoints and networking: Ports without the pain<\/h2>\n
JavaScript apps love their environment variables for port configuration (it’s basically a universal constant). Aspire makes this dead simple:<\/p>\n
var app = builder.AddJavaScriptApp(\"app\", \"..\/app\")\n .WithHttpEndpoint(port: 3000, env: \"PORT\");<\/code><\/pre>\nWhat this does:<\/p>\n
\n- Allocates port 3000 for your app<\/li>\n
- Sets the
PORT<\/code> environment variable<\/li>\n- Registers the endpoint in Aspire’s service discovery (so other services can find you)<\/li>\n
- Makes everything visible in the Aspire dashboard<\/li>\n<\/ul>\n
Common port environment variables you’ll see in the wild:<\/p>\n
\nPORT<\/code> – The universal standard. Express, Fastify, Koa, Next.js, basically everyone uses this<\/li>\nVITE_PORT<\/code> – Vite being Vite<\/li>\nHOST<\/code> – For binding to specific network interfaces (less common but still useful)<\/li>\n<\/ul>\n\ud83d\udd0d Service discovery: Finding your friends in the distributed system<\/h2>\n
This is where things get genuinely cool. JavaScript apps in Aspire automatically participate in service discovery. No configuration files, no service mesh complexity, just straightforward environment variables:<\/p>\n
var api = builder.AddProject<Projects.BackendApi>(\"api\");\n\nvar frontend = builder.AddViteApp(\"frontend\", \"..\/frontend\")\n .WithReference(api);<\/code><\/pre>\nThe frontend automatically receives environment variables like API_HTTP<\/code> and API_HTTPS<\/code>. Connect to your backend without hardcoding URLs (gasp, imagine that):<\/p>\n\/\/ In your Vite\/React application\nconst apiUrl = import.meta.env.API_HTTP || 'http:\/\/localhost:5000';\n\nconst response = await fetch(`${apiUrl}\/api\/data`);\nconst data = await response.json();<\/code><\/pre>\n\ud83d\udd00 Using Vite proxy configuration<\/h3>\n
Alternatively, you can configure Vite to proxy API requests, eliminating the need to manage the API URL in your code. This approach is especially useful during development:<\/p>\n
\/\/ vite.config.ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs\/plugin-react';\n\nexport default defineConfig({\n plugins: [react()],\n server: {\n proxy: {\n '\/api': {\n target: process.env.APISERVICE_HTTP || 'http:\/\/localhost:5000',\n changeOrigin: true,\n secure: false,\n },\n },\n },\n});<\/code><\/pre>\nWith this configuration, your frontend code becomes simpler:<\/p>\n
\/\/ No need to manage apiUrl - just make requests directly\nconst response = await fetch('\/api\/data');\nconst data = await response.json();<\/code><\/pre>\n<\/i>Tip<\/strong><\/p> Using a Vite proxy configuration allows you to make API requests without explicitly managing URLs in your application code. The proxy automatically forwards requests to your backend service based on the environment variables provided by Aspire. <\/div><\/p>\n\ud83d\uddc4\ufe0f Database connections: Connection strings that actually make sense<\/h2>\n
When you wire up databases in Aspire, you get connection information in multiple formats. Why? Because JavaScript’s Database library ecosystem is… diverse (that’s the polite way to put it). Some libraries want URIs, others want individual properties. Aspire gives you both:<\/p>\n
var postgres = builder.AddPostgres(\"postgres\")\n .AddDatabase(\"appdb\");\n\nvar api = builder.AddNodeApp(\"api\", \"..\/api\")\n .WithReference(postgres);\n\nbuilder.AddJavaScriptApp(\"client\", \"..\/client\")\n .WithReference(api);<\/code><\/pre>\nYour Node.js API app gets both URI format and<\/em> individual connection properties:<\/p>\n\/\/ Option 1: Use the URI (perfect for Prisma, TypeORM, etc.)\nconst databaseUrl = process.env.APPDB_URI;\n\/\/ postgresql:\/\/user:pass@host:port\/dbname\n\n\/\/ Option 2: Use individual properties (great for node-postgres)\nconst pool = new Pool({\n host: process.env.APPDB_HOST,\n port: process.env.APPDB_PORT,\n user: process.env.APPDB_USERNAME,\n password: process.env.APPDB_PASSWORD,\n database: process.env.APPDB_DATABASE\n});<\/code><\/pre>\nThis flexibility means you can use Prisma, TypeORM, Sequelize, Knex, node-postgres, or whatever database library you prefer\u2014no Aspire-specific adapters required. It just works with what you’re already using.<\/p>\n
\ud83c\udfdb\ufe0f Default behaviors and publishing: The magic behind the curtain<\/h2>\n
Okay, time for the deep dive. Understanding what Aspire does automatically helps you leverage its full power and tweak things when you need to. (And sometimes you will need to\u2014we’re engineers, we love to tinker.)<\/p>\n
\ud83d\udd27 What every JavaScript resource gets for free<\/h3>\n
Every JavaScript resource you add to Aspire\u2014whether it’s AddJavaScriptApp()<\/code>, AddNodeApp()<\/code>, or AddViteApp()<\/code>\u2014 automatically gets a bunch of sensible Node.js defaults through an internal WithNodeDefaults()<\/code> method. You don’t call this yourself; it happens automatically. Here’s what you’re getting:<\/p>\nOpenTelemetry integration (observability for free):<\/strong><\/p>\nAspire automatically configures OpenTelemetry exporters for your JavaScript apps. Distributed tracing? Metrics collection? You get all of that out of the box. Your Node.js services automatically participate in Aspire’s observability story without you writing a single line of telemetry code. It’s glorious.<\/p>\n
Environment-aware NODE_ENV (because context matters):<\/strong><\/p>\nThe NODE_ENV<\/code> environment variable gets set automatically based on what you’re doing:<\/p>\n\n\"development\"<\/code> when you’re hacking away locally<\/li>\n\"production\"<\/code> when you’re shipping to prod<\/li>\n<\/ul>\nThis ensures frameworks and libraries use appropriate optimizations. Express, for instance, enables template caching and serves less verbose error messages in production. These small optimizations add up.<\/p>\n
Automatic certificate trust (SSL\/TLS without the headaches):<\/strong><\/p>\nAspire handles certificate trust transparently so your Node.js apps can talk to other services over HTTPS during local development without angry certificate warnings:<\/p>\n
\n- \n
Append mode (default)<\/strong>: Sets NODE_EXTRA_CA_CERTS<\/code> to point to Aspire’s certificate bundle. Node.js trusts Aspire-managed certificates alongside<\/em> system certificates. Best of both worlds.<\/p>\n<\/li>\n- \n
Replace mode<\/strong>: Modifies NODE_OPTIONS<\/code> to include --use-openssl-ca<\/code>, forcing Node.js to use OpenSSL’s certificate store instead.<\/p>\n<\/li>\n<\/ul>\nHere’s the clever bit: if you’ve already set NODE_OPTIONS<\/code> to something like --max-old-space-size=4096<\/code> (because you’re dealing with large datasets or memory-hungry builds), Aspire appends<\/em> --use-openssl-ca<\/code> instead of nuking your existing settings. It’s respectful like that.<\/p>\n\ud83d\udc33 Publishing and Dockerfile generation: Production-ready containers without the pain<\/h3>\n
When you publish your Aspire project (to Azure Container Apps, Kubernetes, wherever), Aspire auto-generates production-ready Dockerfiles through PublishAsDockerFile()<\/code>. Smart detail: if you already have a Dockerfile in your app directory, Aspire backs off and uses yours. It’s not going to overwrite your carefully crafted custom setup.<\/p>\nWhat Aspire generates for you:<\/strong><\/p>\nFor AddJavaScriptApp()<\/code> and AddViteApp()<\/code>, you get single-stage Dockerfiles optimized for build tools that spit out static assets:<\/p>\n\n- Base image selection<\/strong>: Defaults to
node:22-slim<\/code> (or detects version from .nvmrc<\/code>, package.json<\/code> engines, or .node-version<\/code>)<\/li>\n- Working directory<\/strong>: Sets up
\/app<\/code> as home base<\/li>\n- Package manager setup<\/strong>: Runs initialization commands (like
corepack enable pnpm<\/code> for pnpm users)<\/li>\n- Smart layer caching<\/strong>: Copies package files first (
package.json<\/code>, lockfiles, etc.) before<\/em> copying source code. This means dependency installation gets cached unless your dependencies actually change. Docker layer caching FTW.<\/li>\n- Dependency installation<\/strong>: Runs your package manager’s install command with BuildKit cache mounts (more on this in a sec)<\/li>\n
- Build execution<\/strong>: Runs your configured build script (default: “build”) to produce production assets<\/li>\n
- Container files<\/strong>: Automatically marks
\/app\/dist<\/code> as a container files source for sharing build outputs between containers<\/li>\n<\/ol>\nFor AddNodeApp()<\/code>, you get multi-stage Dockerfiles that separate build from runtime:<\/p>\n\n- Build stage<\/strong>: Named “build”, uses the full Node.js image, installs deps, runs build scripts<\/li>\n
- Runtime stage<\/strong>: Named “runtime”, copies only<\/em> built artifacts from the build stage (smaller images, faster deploys)<\/li>\n
- Security hardening<\/strong>: Switches to the non-privileged
node<\/code> user before running anything<\/li>\n- Production environment<\/strong>: Sets
NODE_ENV=production<\/code> explicitly<\/li>\n- Clean entrypoint<\/strong>: Configures as
[\"node\", \"your-script.js\"]<\/code> for efficient process execution<\/li>\n<\/ol>\nBuildKit cache mount magic:<\/strong><\/p>\nAspire leverages Docker BuildKit’s cache mount feature for package managers. This is a game-changer for build times:<\/p>\n
\n- npm:
--mount=type=cache,target=\/root\/.npm<\/code><\/li>\n- Yarn v1:
--mount=type=cache,target=\/root\/.cache\/yarn<\/code><\/li>\n- Yarn v2+:
--mount=type=cache,target=.yarn\/cache<\/code><\/li>\n- pnpm:
--mount=type=cache,target=\/pnpm\/store<\/code><\/li>\n<\/ul>\nThese cache mounts persist package manager caches across builds<\/em>. Translation: you only download packages that actually changed. Subsequent builds are dramatically faster because you’re not re-downloading React for the 500th time.<\/p>\nSmart build script execution:<\/strong><\/p>\nAddJavaScriptApp()<\/code> and AddViteApp()<\/code> automatically configure build scripts for you, so your apps build without extra configuration. For AddNodeApp()<\/code>, you’ll need to explicitly call WithBuildScript()<\/code> if you want a build step. If no build script is configured, the generated Dockerfile skips that step entirely. Perfect for apps that don’t need a compilation or bundling step\u2014why waste build time on something unnecessary?<\/p>\n