[BUG] Inconsistent singleFile behaviour

[michael-ball-ctct]

Describe the bug.

Currently, using the HTML-Template to generate docs, and using the singleFile: 'false' option behaves very weirdly. If it's either 'true' or true then it's fine, but if it's 'false' or false it doesn't behave as you would expect in either case.

The docs for @asyncapi/html-template state this value should be a string.

If it's a string of 'false' (which is a truthy value - likely partially the source of the issue), it incorrectly generates the index.html as the singleFile format - the same as if you were to use a truthy value. However, it ALSO generates the docs as external dependencies, as you would expect it to when the value is set to false.

If it's a boolean of false then it correctly generates the file without the dependencies inside of it, like you would expect. However, it does not generate the external dependencies which it needs to work.

Tested using versions:
Node v22.2.0
@asyncapi/generator: 2.7.0
@asyncapi/parser: 3.4.0
@asyncapi/html-template on 2025-07-11 (so probably pulling v3.3.0)

Stretch goal:

It would also be a nice value add to me if there were additional options to:

1. intentionally generate the minimal documentation without the external dependencies, for the use case where I'm generate a bunch of different documentation and wish to point it all to the same self-hosted JS/CSS dependencies. This means I can save space and time when generating docs.
2. generate only the dependencies, which I can run when I build and deploy the server I host those dependencies on.

I understand my use case may not be worth specifically catering to. I can cope with that, it's just a nice-to-have.

Expected behavior

Both false and 'false' behave the same, and generate the minimal documentation which relies on external deps, and also generate those deps.

Screenshots

How to Reproduce

https://github.com/michael-ball-ctct/async-api-generator-singlefile-bug-demo

1. Clone minimal repoduction and navigate to its directory.
2. npm install.
3. npm run start.
4. Read test output/inspect files generated in ./docs

🖥️ Device Information [optional]

• Operating System (OS): Ubuntu 22.04.5 LTS
• Browser: N/A
• Browser Version: N/A

👀 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!

NB: In theory, I'm happy to contribute a PR to help push this along. In practice, I'm not really even sure where to start with this as I don't have a deep understanding of the internals of AsyncAPI, and I'm unsure how much time I'll be able to dedicate to this.

[derberg]

Thanks for the report.

singleFile is configured and set by default to false in here: https://github.com/asyncapi/html-template/blob/master/package.json#L90-L94

here you have a conditional configuration that decides when css and js folders are generated: https://github.com/asyncapi/html-template/blob/master/package.json#L63-L76

some more singleFile conditions are in https://github.com/asyncapi/html-template/blob/master/components/index.js - look for params?.singleFile

Probably the fix is to introduce a variable where a condition like params?.singleFile is more sophisticated and also validates false explicitly or maybe whatever is passed in singleFile is casted to bool first.

You can easily test if your work on a PR locally with your test project. The Generator picks up tempates from any location, just like npm install so you can just point to local fork of html-template like ./mydir/forks/html-template (just you need to install template dependencies, as when referenced from local, installation is not performed by generator).

And huge request - first please focus on the bug, later on features. While solving the bug you will understand basics, that will help you think on the features ideas you had. So please open PR only for bug fix, and for the other ideas first share how you would suggest they will be implemented

[derberg]

I'm transfering this issue to html-template repo

[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.

[michael-ball-ctct]

Thanks for the guidance - it proved immensely valuable.

I had already had a cursory look through the template to try and find where singleFile was being consumed, but obviously didn't do a good enough job.

I ended up only fixing the 'false' string case and not the false boolean case. It looks like the fix for that would possibly be somewhere in the generator project, and also the API of those optional params appears to only expect strings so it would be out of scope.

[derberg]

yeah, it's easy when generator is used on a CLI level, then all the inputs are strings anyway. Things get a bit more complex on library level.

lemme have a look at the PR

[asyncapi-bot]

🎉 This issue has been resolved in version 3.3.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀