ecoDriverltd/FoundryAgentsExperiment / .agents/skills/aspire-deployment
aspire-deployment
Flagged**WORKFLOW SKILL** — Deploy Aspire apps from AppHost models to Docker Compose, Kubernetes, Azure, or AWS. WHEN: "deploy Aspire app", "publish Aspire artifacts", "deploy to Azure Container Apps", "generate Kubernetes artifacts", "tear down Aspire deployment". INVOKES: aspire CLI, Aspire docs, target cloud/container CLIs. FOR SINGLE OPERATIONS: use generic Azure, Kubernetes, Docker, or AWS tools only when no Aspire AppHost exists.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.6 KB |
| references/aws.md | markdown | 8.4 KB |
| references/azure.md | markdown | 19.1 KB |
| references/cicd.md | markdown | 14.4 KB |
| references/docker-compose.md | markdown | 6.8 KB |
| references/github-actions-azure-csharp.yml | config | 1.6 KB |
| references/github-actions-azure-typescript.yml | config | 1.5 KB |
| references/javascript.md | markdown | 7.9 KB |
| references/kubernetes.md | markdown | 13.4 KB |
| references/preflight.md | markdown | 9.6 KB |
references/javascript.md
View on GitHub# JavaScript app deployment
Use this reference whenever an Aspire deployment includes JavaScript app resources, such as Vite, React, Vue, Angular, Astro, Next.js, Nuxt, or plain Node.js apps.
JavaScript resources are not just another deployment target. They need an explicit production serving model before the target reference can be trusted. A Vite dev server that works during `aspire run` is often build-only during publish/deploy unless the AppHost says who serves the built files.
## Integration to add
```bash
aspire add javascript
```
This adds `Aspire.Hosting.JavaScript`, which provides `AddJavaScriptApp`, `AddNodeApp`, `AddViteApp`, `AddNextJsApp`, package-manager helpers, and JavaScript publish modes.
## Docs to load
Always start with current docs:
```bash
aspire docs search "javascript deployment"
aspire docs get "deploy-javascript-apps"
aspire docs get "set-up-javascript-apps-in-the-apphost"
```
Use API docs before editing. Search in the AppHost language you detected:
```bash
aspire docs api search "AddJavaScriptApp" --language csharp
aspire docs api search "AddJavaScriptApp" --language typescript
aspire docs api search "AddNodeApp" --language csharp
aspire docs api search "AddNodeApp" --language typescript
aspire docs api search "AddViteApp" --language csharp
aspire docs api search "AddViteApp" --language typescript
aspire docs api search "AddNextJsApp" --language csharp
aspire docs api search "AddNextJsApp" --language typescript
aspire docs api search "PublishAsStaticWebsite" --language csharp
aspire docs api search "PublishAsStaticWebsite" --language typescript
aspire docs api search "PublishAsNodeServer" --language csharp
aspire docs api search "PublishAsNodeServer" --language typescript
aspire docs api search "PublishAsPackageScript" --language csharp
aspire docs api search "PublishAsPackageScript" --language typescript
aspire docs api search "PublishWithContainerFiles" --language csharp
aspire docs api search "PublishWithContainerFiles" --language typescript
aspire docs api search "PublishWithStaticFiles" --language csharp
aspire docs api search "PublishWithStaticFiles" --language typescript
```
## Setup
Use `Aspire.Hosting.JavaScript` for Aspire 13+ apps. `Aspire.Hosting.NodeJs` is the old package name; do not add it for new guidance unless the target repo is intentionally pinned to older Aspire.
## Resource choice
Choose the AppHost resource based on what the JavaScript app is during local development:
| Resource | Use when | C# shape | TypeScript shape |
|----------|----------|----------|------------------|
| JavaScript app | Generic package-script-driven app | `AddJavaScriptApp(...)` | `addJavaScriptApp(...)` |
| Node app | A Node process starts a specific script file | `AddNodeApp(...)` | `addNodeApp(...)` |
| Vite app | Vite-based browser app or framework dev server | `AddViteApp(...)` | `addViteApp(...)` |
| Next.js app | Next.js app using the dedicated helper | `AddNextJsApp(...)` | `addNextJsApp(...)` |
`AddNextJsApp` and JavaScript publish methods are experimental. In C# AppHosts, follow docs for the `ASPIREJAVASCRIPT001` suppression instead of suppressing warnings broadly.
## Production serving model
Choose the production entrypoint before deploying:
| Production shape | Use when | AppHost pattern |
|------------------|----------|-----------------|
| Static frontend served by a backend | The backend should serve built frontend files from `wwwroot`, `static`, or similar | Backend resource uses `PublishWithContainerFiles(frontend, "<path>")` |
| Static frontend served by a gateway/BFF | YARP or another proxy is the public entrypoint and serves the built frontend | Gateway uses `PublishWithStaticFiles(frontend)` |
| Static frontend served by the JavaScript resource | The frontend should deploy as its own static website/container | JavaScript resource uses `PublishAsStaticWebsite(...)` |
| SSR or Node.js server with built output | The framework emits a server entrypoint/artifact | JavaScript resource uses `PublishAsNodeServer(...)` |
| SSR or Node.js server started by package script | Runtime needs package manager scripts and runtime dependencies | JavaScript resource uses `PublishAsPackageScript(...)` |
| Next.js standalone app | Next.js is configured for standalone output | Use `AddNextJsApp(...)` |
Do not assume the Vite dev server is the production server. During publish/deploy, Vite resources usually build static files unless the AppHost selects a JavaScript publish mode.
## Code changes to make
1. Run `aspire add javascript` if the AppHost does not already reference the JavaScript hosting integration.
2. Add the appropriate JavaScript resource.
C# AppHost examples:
```csharp
var frontend = builder.AddViteApp("frontend", "./frontend");
var api = builder.AddNodeApp("api", "./api", "server.js")
.WithHttpEndpoint(env: "PORT");
```
TypeScript AppHost examples:
```typescript
const frontend = await builder.addViteApp("frontend", "./frontend");
const api = await builder
.addNodeApp("api", "./api", "server.js")
.withHttpEndpoint({ env: "PORT" });
```
3. Configure package manager and scripts only when defaults are wrong:
- C#: `WithNpm(...)`, `WithYarn(...)`, `WithPnpm(...)`, `WithBun(...)`, `WithBuildScript(...)`, `WithRunScript(...)`.
- TypeScript: `withNpm(...)`, `withYarn(...)`, `withPnpm(...)`, `withBun(...)`, `withBuildScript(...)`, `withRunScript(...)`.
4. Add a production serving model from the table above. This is required for build-only browser apps.
5. Add `WithExternalHttpEndpoints()` / `withExternalHttpEndpoints()` only to the resource that owns the public production HTTP surface, such as the backend, gateway, static website, Node server, or Next.js app.
6. Keep dev-only gateway/proxy wiring behind run-mode checks when it depends on a dev server URL. Production routing must be configured on the production-serving resource, not assumed from Vite dev proxy settings.
7. After choosing the production-serving resource, apply the target reference for Docker Compose, Kubernetes, Azure, or AWS.
## Target-specific notes
- Docker Compose: JavaScript resources can publish as containers or static-file-carrying build resources. Inspect generated Dockerfiles, `docker-compose.yaml`, and `.env` placeholders.
- Kubernetes and Azure Kubernetes Service (AKS): make sure the production-serving resource becomes the workload with the service/ingress/gateway exposure. Build-only resources must be consumed by another deployable resource or converted with a JavaScript publish method.
- Azure Container Apps: only the production-serving compute resource should be external. For static browser apps, `PublishAsStaticWebsite(...)` can be the external resource; for backend-served or gateway-served apps, the backend/gateway is the external resource.
- Azure App Service: use this only when the JavaScript app fits the public website model and single target-port constraints. SSR/Node apps need the right startup script/output and external HTTP endpoint.
- AWS: verify support in the AWS integrations repo. Do not assume the AWS preview deployment supports every JavaScript publish mode.
## Common pitfalls
- A Vite resource that works locally can fail deployment validation if it is still build-only and no deployed resource consumes its files.
- Vite dev-server proxy configuration does not automatically become production routing.
- `PublishWithContainerFiles(...)` copies built files into a destination container; the destination app still needs to serve those files.
- `PublishWithStaticFiles(...)` is for gateway/BFF resources such as YARP serving frontend files.
- `PublishAsPackageScript(...)` keeps runtime package dependencies and is larger than a built Node server output; prefer `PublishAsNodeServer(...)` when the framework emits a runnable server artifact.
- Next.js standalone deployment requires Next.js standalone output configuration. Validate this before deploying.
- Do not expose both a dev frontend resource and the production-serving gateway/backend unless the user intentionally wants two public surfaces.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |