Update Samples

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:

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

Services & Technologies

Azure Services

Frameworks & Features

4. Output format

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

[
  {
    "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

7. Integration with build

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

pnpm update:samples

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