update-samples

---
name: update-samples
description: Update the samples data file by fetching sample metadata from the microsoft/aspire-samples GitHub repository. Use when adding new samples, refreshing sample data, or ensuring samples.json stays in sync with the upstream repo.
---

# Update Samples Data

This skill synchronizes the samples data file with the `microsoft/aspire-samples` GitHub repository. It enumerates all sample projects in the `samples/` directory, fetches each sample's README.md, and generates a structured JSON catalog.

## Overview

The aspire.dev site maintains a data file for samples:

- **`src/frontend/src/data/samples.json`** — Sample metadata including titles, descriptions, tags, deep links, and README content extracted from the upstream repo.

This skill keeps that file in sync with the `microsoft/aspire-samples` repository on GitHub.

## Prerequisites

- Node.js installed and available on `PATH`
- Working directory is the repository root
- The frontend project dependencies are installed (`pnpm install` in `src/frontend/`)
- Optional: `GITHUB_TOKEN` environment variable for higher GitHub API rate limits

## Step-by-Step Process

### 1. Run the update script

Fetch the latest sample data from the GitHub API:

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

This writes updated sample metadata to `src/frontend/src/data/samples.json`. The script queries the GitHub Contents API for directories in `microsoft/aspire-samples/samples/`, fetches each sample's README.md, and extracts structured metadata.

### 2. What the script does

For each subdirectory in `samples/`:

1. **Lists directories** — Calls the GitHub Contents API to enumerate entries in `samples/` and filters to directories only (skipping files like `global.json`, `Directory.Build.props`).

2. **Fetches README.md** — Downloads the raw README.md for each sample directory.

3. **Extracts metadata** from the README:
   - **`name`** — The directory name (e.g., `aspire-shop`)
   - **`title`** — Extracted from the first `# heading` in the README
   - **`description`** — The first paragraph of body text after the title (before any `##` heading)
  - **`href`** — Deep link to the sample on GitHub: `https://github.com/microsoft/aspire-samples/tree/main/samples/{name}`
   - **`readme`** — The full Markdown content of the README.md, with image paths rewritten to local assets (see below)
   - **`tags`** — Auto-detected tags based on technologies, languages, services, and features mentioned in the README and directory name
   - **`thumbnail`** — Local asset path to the first image referenced in the README (if any), or `null`

4. **Downloads images** — For each image referenced in the README (`![alt](src)`):
   - Resolves the remote URL (relative paths are resolved against the GitHub raw content URL)
   - Downloads the image to `src/frontend/src/assets/samples/{name}/{filename}`
   - Rewrites the image reference in the README to use the local asset path: `~/assets/samples/{name}/{filename}`
   - This ensures images are bundled with the site and served locally rather than hotlinked from GitHub

5. **Writes output** — Saves the result as a sorted JSON array to `src/frontend/src/data/samples.json`.

### 3. Tag detection

Tags are automatically inferred from the README content and sample name. The script detects:

#### Languages
| Tag | Matched by |
|---|---|
| `csharp` | C#, .NET references |
| `python` | Python references |
| `javascript` | JavaScript references |
| `node` | Node.js references |
| `go` | Go/Golang references |

#### Services & Technologies
| Tag | Matched by |
|---|---|
| `redis` | Redis references |
| `postgresql` | PostgreSQL, Postgres, Npgsql references |
| `sql-server` | SQL Server, MSSQL references |
| `mysql` | MySQL references |
| `mongodb` | MongoDB references |
| `rabbitmq` | RabbitMQ references |
| `kafka` | Kafka references |
| `prometheus` | Prometheus references |
| `grafana` | Grafana references |
| `docker` | Docker, container references |

#### Azure Services
| Tag | Matched by |
|---|---|
| `azure` | Azure references |
| `azure-functions` | Azure Functions references |
| `azure-storage` | Azure Storage references |
| `azure-service-bus` | Azure Service Bus references |

#### Frameworks & Features
| Tag | Matched by |
|---|---|
| `blazor` | Blazor references |
| `orleans` | Orleans references |
| `grpc` | gRPC references |
| `ef-core` | Entity Framework Core references |
| `metrics` | Metrics, OpenTelemetry references |
| `health-checks` | Health check references |
| `containers` | Container build/deployment references |
| `databases` | Database-related references |
| `migrations` | Database migration references |
| `volumes` | Volume mount references |
| `dashboard` | Dashboard references |

### 4. Output format

The output `samples.json` is a JSON array with entries like:

```json
[
  {
    "name": "aspire-shop",
    "title": "Aspire Shop",
    "description": "The app consists of four .NET services including a Blazor frontend, catalog API, catalog database manager, and basket service.",
    "href": "https://github.com/microsoft/aspire-samples/tree/main/samples/aspire-shop",
    "readme": "# Aspire Shop\n\n![Screenshot...](~/assets/samples/aspire-shop/aspireshop-frontend-complete.png)...",
    "tags": ["csharp", "blazor", "postgresql", "redis", "grpc", "ef-core"],
    "thumbnail": "~/assets/samples/aspire-shop/aspireshop-frontend-complete.png"
  }
]
```

### 5. Manual review

After running the script:

- **Review new entries** — Verify titles and descriptions are meaningful
- **Check tags** — The auto-detection may miss niche technologies; manually add tags if needed
- **Verify thumbnails** — Ensure image URLs resolve correctly
- **Remove stale samples** — The script automatically handles this since it rebuilds from source

### 6. Environment variables

| Variable | Required | Description |
|---|---|---|
| `GITHUB_TOKEN` | No | GitHub personal access token for higher API rate limits (60 → 5000 requests/hour) |
| `SAMPLES_BRANCH` | No | Override the `microsoft/aspire-samples` ref to fetch from (default `main`). Useful for staging `samples.json` against a still-open upstream PR — set to the PR's head ref. The generated `href` fields stay anchored to `main` so links remain valid after the PR branch is deleted. |

### 7. Integration with build

The script is registered as an npm script in `src/frontend/package.json`:

```bash
pnpm update:samples
```

It is also included in the `update:all` aggregate script so it runs alongside other data updates during builds.