---
name: update-integrations
description: Update integration documentation links and API reference data by synchronizing NuGet package names with their documentation URLs and generating per-package API schemas. Use when adding new integrations, refreshing package data, ensuring integration-docs.json stays in sync with aspire-integrations.json, or regenerating API reference JSON files.
---

# Update Integration Documentation Links & API Reference Data

This skill synchronizes the integration package catalog with documentation URL mappings and generates per-package API reference schemas. It ensures every NuGet package listed in the integrations data file has a corresponding documentation link and an up-to-date API reference JSON file.

## Overview

The aspire.dev site maintains three key data locations:

- **`src/frontend/src/data/aspire-integrations.json`** — Package metadata fetched from the configured package feeds (titles, descriptions, icons, versions, download counts).
- **`src/frontend/src/data/integration-docs.json`** — Mappings from package names to site-relative documentation URLs.
- **`src/frontend/src/data/pkgs/`** — Per-package API reference JSON files (e.g. `Aspire.Hosting.Redis.13.1.2.json`) generated by the `PackageJsonGenerator` tool. These feed the auto-generated API reference pages at `/reference/api/`.
- **`src/frontend/src/data/ts-modules/`** — Per-package TypeScript API reference JSON files (e.g. `Aspire.Hosting.Redis.13.2.0.json`) generated by the `AtsJsonGenerator` tool. These feed the auto-generated TypeScript API reference pages at `/reference/api/typescript/`.
- **`src/frontend/src/data/twoslash/aspire.d.ts`** — A single consolidated TypeScript declaration bundle generated from the `ts-modules` JSON by `scripts/generate-twoslash-types.ts`. Consumed by `expressive-code-twoslash` to provide hover tooltips for TypeScript code samples in the docs. **Source-controlled** — commit the diff whenever `ts-modules` changes.

This skill keeps the documentation mappings in sync with the package catalog and regenerates both the C# and TypeScript API reference data.

## Prerequisites

- Node.js installed and available on `PATH`
- .NET SDK installed and available on `PATH` (required for the `PackageJsonGenerator` tool)
- PowerShell (pwsh) available on `PATH` (for running the generation script)
- Working directory is the repository root
- The frontend project dependencies are installed (`pnpm install` in `src/frontend/`)

### Release branch package source behavior

- On `main` and all non-`release/*` branches, official Aspire packages resolve from `https://api.nuget.org/v3/index.json`
- On `release/*` branches, official packages (`Aspire.*`) must resolve from the branch-specific public Azure Artifacts feed instead of nuget.org
- Community Toolkit packages (`CommunityToolkit.Aspire.*`) always resolve from nuget.org
- The branch name in this repo is expected to match the corresponding branch in `microsoft/aspire` (for example `release/13.2`)
- The release feed name follows `darc-pub-dotnet-aspire-{shortSha}` where `{shortSha}` is the first 8 characters of the head commit SHA for the matching Aspire release branch
- The automation derives the NuGet service index from that feed name as `https://pkgs.dev.azure.com/dnceng/public/_packaging/{feed-name}/nuget/v3/index.json`

#### Release feed resolution

The scripts use this precedence on `release/*` branches:

1. `ASPIRE_RELEASE_FEED_URL` — accepts the full NuGet service index URL, the Azure DevOps feed page URL, or the raw feed name
2. `ASPIRE_RELEASE_FEED_NAME` — explicit feed name such as `darc-pub-dotnet-aspire-aad16017`
3. `ASPIRE_RELEASE_COMMIT` / `ASPIRE_RELEASE_COMMIT_SHA` — derives the feed name from the commit SHA prefix
4. Automatic lookup of the matching branch head via `git ls-remote` against `https://github.com/microsoft/aspire`

If the Aspire release branch is not publicly reachable yet, set one of the override environment variables above. The scripts intentionally fail on `release/*` if the official release feed cannot be resolved, to avoid accidentally ingesting stale nuget.org packages.

## Step-by-Step Process

### 1. Run the update script

Fetch the latest package data from the configured package feeds:

```bash
cd src/frontend && node scripts/update-integrations.js
```

This writes updated package metadata to `src/frontend/src/data/aspire-integrations.json`. The script queries the NuGet v3 API for packages matching `owner:aspire`, `Aspire.Hosting.`, and `CommunityToolkit.Aspire`, then filters out deprecated, unlisted, and excluded packages.

On `release/*` branches, the script queries the branch-specific official Aspire feed for `Aspire.*` packages and continues to query nuget.org for `CommunityToolkit.Aspire.*` packages.

### 2. Read the updated package data

Load `src/frontend/src/data/aspire-integrations.json` and extract all package names from the `title` field of each entry in the JSON array.

### 3. Update integration documentation mappings

Load `src/frontend/src/data/integration-docs.json` and reconcile it with the package list:

- **For each package name** (from `title` field) in `aspire-integrations.json`:
  - Check if a matching entry exists in `integration-docs.json` (where `match` equals the package name)
  - If an entry exists, verify the `href` is correct
  - If no entry exists, determine the appropriate documentation URL

- **Remove stale entries** from `integration-docs.json` that reference packages no longer in `aspire-integrations.json`

- **Preserve existing correct mappings** — do not change entries that are already accurate

### 4. Determining documentation URLs

When a package has no existing mapping, determine the URL based on:

#### Package name patterns

| Package prefix | Documentation path pattern |
|---|---|
| `Aspire.Hosting.Azure.*` | `/integrations/cloud/azure/{service-name}/` |
| `Aspire.Azure.*` | `/integrations/cloud/azure/{service-name}/` |
| `Aspire.Hosting.{Tech}` | `/integrations/{category}/{tech}/` |
| `Aspire.{Client}.{Driver}` | `/integrations/{category}/{tech}/` |
| `CommunityToolkit.Aspire.Hosting.*` | `/integrations/{category}/{tech}/` |
| `CommunityToolkit.Aspire.*` | `/integrations/{category}/{tech}/` |

#### Technology categories

The documentation site organizes integrations into these categories:

| Category path | Technologies |
|---|---|
| `/integrations/ai/` | OpenAI, Ollama, Milvus, Qdrant |
| `/integrations/caching/` | Redis, Valkey, Garnet, Memcached |
| `/integrations/cloud/azure/` | All Azure services |
| `/integrations/compute/` | Orleans, Dapr |
| `/integrations/databases/` | PostgreSQL, SQL Server, MySQL, MongoDB, Cosmos DB, Oracle, Elasticsearch, Milvus, Qdrant |
| `/integrations/databases/efcore/` | EF Core variants of database integrations |
| `/integrations/devtools/` | Developer tools and utilities |
| `/integrations/frameworks/` | Framework integrations |
| `/integrations/messaging/` | Kafka, RabbitMQ, NATS, Azure Service Bus, Event Hubs |
| `/integrations/observability/` | OpenTelemetry, Seq, logging |
| `/integrations/reverse-proxies/` | YARP |
| `/integrations/security/` | Keycloak, Key Vault |

#### URL resolution strategy

1. Match against existing similar package mappings in `integration-docs.json`
2. Infer from the package name and technology category
3. **Verify the page exists** — use Playwright MCP tools or check the file system under `src/frontend/src/content/docs/` to confirm the target page is real
4. If no valid documentation page can be found, flag the package for manual review

### 5. Generate API reference data

After updating the integration catalog, regenerate the per-package API reference JSON files. The `generate-package-json.ps1` script automates this:

```bash
cd src/tools/PackageJsonGenerator && pwsh ./generate-package-json.ps1
```

The script performs the following for every package listed in `aspire-integrations.json`:

1. Resolves the correct package source per package: official Aspire packages use the branch-specific release feed on `release/*`, while Community Toolkit packages continue to use nuget.org.
2. Queries that package source for the latest stable version (falls back to latest preview if no stable exists).
3. Downloads the package into the local NuGet cache via `dotnet restore` if not already cached.
4. Selects the best-matching target framework folder (prefers `net10.0`, then `net9.0`, etc.).
5. Uses Roslyn to analyze the assembly and extract all public types, members, XML docs, and attributes.
6. Writes a `{Package}.{Version}.json` file to `src/frontend/src/data/pkgs/`.

The generated JSON follows this schema:

```json
{
  "package": {
    "name": "Aspire.Hosting.Redis",
    "version": "13.1.2",
    "targetFramework": "net10.0"
  },
  "types": [
    {
      "name": "TypeName",
      "fullName": "Namespace.TypeName",
      "namespace": "Namespace",
      "kind": "class",
      "accessibility": "public",
      "members": [ ... ],
      "docs": { ... }
    }
  ]
}
```

These files are consumed by the `packages` content collection defined in `src/frontend/src/content.config.ts` and used to render API reference pages at `/reference/api/{package}/{type}/`.

#### Selective regeneration

To regenerate API data for specific packages only:

```bash
pwsh ./generate-package-json.ps1 -Packages @("Aspire.Hosting.Redis", "Aspire.Hosting.PostgreSQL")
```

#### Targeting a different framework

To use a different target framework (e.g. `net10.0`):

```bash
pwsh ./generate-package-json.ps1 -Framework "net10.0"
```

#### Handling failures

The script reports a summary of successes, failures, and skipped packages. Common reasons for skips or failures:

- Package has no `lib/` folder (meta-packages, build-only packages)
- No DLLs found for the preferred TFM
- NuGet API resolution failure

Packages that fail should be investigated individually — they may need a different framework target or may not ship a public API surface.

If an official release feed is required but not yet publicly reachable, rerun with one of the release feed override environment variables set.

### 5a. Generate TypeScript API reference data

After updating `aspire-integrations.json`, regenerate the TypeScript API reference JSON files for the hosting packages that expose ATS capabilities:

```bash
cd src/frontend && node scripts/update-ts-api.js
```

The companion `generate-ts-api-json.ps1` script reads the generated C# package JSON files in `src/frontend/src/data/pkgs/`, selects `Aspire.Hosting` and `Aspire.Hosting.*` packages, and passes each package/version through to `aspire sdk dump`. This keeps `src/frontend/src/data/ts-modules/` aligned with the same package set and versions that already flowed through C# API generation.

When a TypeScript module is regenerated for a new package version, stale `ts-modules` JSON files for older versions of that same package are deleted automatically.

After the JSON is refreshed, `update-ts-api` automatically chains `generate-twoslash-types.ts` to rebuild `src/frontend/src/data/twoslash/aspire.d.ts`. This bundle is source-controlled and its diff must be committed alongside the `ts-modules` JSON changes — without it, docs hover tooltips fall back to `any`. If you only need to refresh the bundle (e.g. after a generator script change) without running the full SDK dump, use:

```bash
cd src/frontend && pnpm twoslash-types
```

### 6. Verify all links

For every entry in the updated `integration-docs.json`:

- **Site-relative links** must end with a trailing `/`
- **External links** (e.g., AWS docs) are allowed and should use full URLs
- **All site-relative links must point to existing documentation pages** — check by verifying a corresponding `.mdx` file exists under `src/frontend/src/content/docs/`

Do not assume a page exists without verification.

### 7. Save the result

Write the updated `integration-docs.json` maintaining consistent formatting (2-space indentation, trailing newline). The API reference JSON files in `src/frontend/src/data/pkgs/` are written directly by the generation script and require no additional save step.

## Entry format

Each entry in `integration-docs.json` follows this structure:

```json
{
  "match": "Aspire.Hosting.Redis",
  "href": "/integrations/caching/redis/"
}
```

- `match` — The exact NuGet package name (from the `title` field in `aspire-integrations.json`)
- `href` — A site-relative path (with trailing `/`) or an external URL

## Handling unmapped packages

When a package name has no clear documentation mapping:

1. **Do not invent a URL** — only use paths that correspond to real pages
2. **List the package** for manual review with a note explaining why no mapping was found
3. These packages likely need new documentation pages written (hand off to the `doc-writer` skill)

## Example output

After running this skill, the agent should report:

- Number of packages in `aspire-integrations.json`
- Number of mapped entries in `integration-docs.json`
- Any new mappings added
- Any stale mappings removed
- Any packages that could not be mapped (flagged for manual review)
- Number of API reference JSON files generated (success / failed / skipped)
- Any packages that failed API generation, with reasons
- Confirmation that `src/frontend/src/data/twoslash/aspire.d.ts` was refreshed (and that the diff will be committed)