Quickstart

This guide is dual-language. Pick the AppHost flavour you want and the rest of the page will follow your choice.

1. Scaffold an AppHost

C#

mkdir MyAppHost && cd MyAppHost
aspire init
aspire add IEvangelist.Aspire.Hosting.Netlify
aspire add Aspire.Hosting.JavaScript

aspire init drops a minimal C# AppHost project. aspire add adds the hosting integrations (and updates the AppHost’s .csproj).

TypeScript

mkdir MyAppHost && cd MyAppHost
aspire init
aspire add IEvangelist.Aspire.Hosting.Netlify
aspire add Aspire.Hosting.JavaScript

aspire init drops apphost.mts, aspire.config.json, package.json, tsconfig.apphost.json, and a .aspire/modules/ folder for generated TypeScript surface bindings (the CLI will prompt you to choose TypeScript). aspire add registers each integration in aspire.config.json and regenerates .aspire/modules/.

2. Wire up your frontend

Drop your built static frontend (e.g. an Astro dist/ folder) next to the AppHost, then point at it:

C#

using Aspire.Hosting;
using Aspire.Hosting.JavaScript;

var builder = DistributedApplication.CreateBuilder(args);

// Optional: bind an auth token from configuration / user secrets.
var authToken = builder.AddParameterFromConfiguration(
    "netlify-token", "NETLIFY_AUTH_TOKEN", secret: true);

builder.Pipeline.AddNetlifyDeployPipeline();

builder.AddJavaScriptApp("astro", "../astro")
    .PublishAsNetlifySite("dist", authToken);

builder.Build().Run();

The single-argument overload of PublishAsNetlifySite is shorthand for new NetlifyDeployOptions { Dir = "dist", NoBuild = true }. Use the full NetlifyDeployOptions form when you need a Site, Message, or Production flag.

TypeScript

// apphost.mts
import { createBuilder } from "./.aspire/modules/aspire.mjs";

const builder = await createBuilder();

const authToken = await builder.addParameterFromConfiguration(
  "netlify-token", "NETLIFY_AUTH_TOKEN", { secret: true });

await builder.pipeline().addNetlifyDeployPipeline();

const astro = await builder.addJavaScriptApp("astro", "../astro");
await astro
  .publishAsNetlifySite({ dir: "dist", noBuild: true }, { authToken });

await builder.build().run();

Aspire 13.4 projects this integration’s [AspireExport]-annotated surface into TypeScript through .aspire/modules/aspire.mjs. The publishAsNetlifySite, addNetlifyDeployPipeline, withNpmCommand, and withNpmRunCommand functions are generated automatically.

3. Run locally

aspire run

Aspire starts your frontend’s dev server alongside the dashboard. Browse to the dashboard URL printed in the terminal to inspect the resource tree.

4. Deploy

aspire deploy

The pipeline:

1. Resolves the Netlify CLI (auto-installs if missing).
2. Resolves your auth token (parameter > env var > ntl login).
3. Resolves the Netlify site ID (or creates a new site).
4. Runs netlify deploy ... and records the result.

See Configuration for the full list of options, and Authentication for the precedence rules.

Working samples

Both flavours have a runnable sample in the repo. Clone and run:

C#

samples/Quickstart.AppHost

aspire run --apphost samples/Quickstart.AppHost/Quickstart.AppHost.csproj

TypeScript

samples/Quickstart.AppHost.TypeScript

aspire run --apphost samples/Quickstart.AppHost.TypeScript/apphost.mts