[BUG] Optimizing build process: Skip redundant AsyncAPI examples fetching

[Satya900]

Describe the bug.

Currently, the scripts/fetch-asyncapi-example.js script runs as part of the npm run build process.

This script downloads a ZIP file from GitHub, unzips it, and parses every YAML file to generate:

assets/examples/examples.json

This process runs on every build, even when the examples have already been fetched and generated.

---

Problem Statement

The scripts/fetch-asyncapi-example.js script executes during the build process (via prebuild or a direct invocation).

Script workflow

• Downloads a ZIP file from GitHub
• Unzips the archive
• Parses every YAML file
• Generates assets/examples/examples.json

On every build, this entire workflow is repeated — regardless of whether the examples already exist locally.

---

Issues Identified

• Slower build times
  Particularly impactful for developers with slower internet connections.

• Unnecessary network traffic
  Static assets are re-downloaded on every build.

• Flaky builds
  If GitHub is temporarily unreachable, the build fails entirely.

---

Proposed Solution

Optimize the script to check for the existence of previously fetched examples before performing network operations.

---

Enhancements

• Add a check to verify whether:

assets/examples/examples.json

exists and is not empty.

If the file exists

• Skip the download step
• Skip extraction
• Skip YAML parsing

---

Manual Override Support

Add a CLI flag to allow developers to force refresh the examples:

--force
# or
-f

This enables manual regeneration when updates are required.

Expected behavior

• Faster local development
  Subsequent builds skip the network-heavy fetching process.

• Improved build stability
  Builds won’t fail due to transient network issues if examples are already cached.

• Reduced bandwidth usage
  Eliminates repeated downloads of static assets.

• Developer control
  The --force / -f flag enables manual refresh when updates are needed.

Screenshots

....

How to Reproduce

1. Run npm run build or node scripts/fetch-asyncapi-example.js.
2. Observe the network activity and time taken to fetch/unzip examples.
3. Run the same command again immediately after.
4. Observe that it repeats the entire download and extraction process instead of reusing existing files.

🖥️ Device Information [optional]

• Operating System: Windows 10/11
• Node Version: ≥ 24

👀 Have you checked for similar open issues?

• I checked and didn't find similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue ?

Yes I am willing to submit a PR!

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.