asyncapi / asyncapi/cli

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

Open
#2,015 3 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
272
Forks
375
Avg merge
3h 22m
Merged PRs (30d)
8

Description

## 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:

```bash
--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?

- [x] I checked and didn't find similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue ?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.