[FEATURE] introduce new command asyncapi start preview

[derberg]

Why do we need this improvement?

ATM we have asyncapi start studio. It is cool, starts local Studio editor, so people can edit in browser. Problem is that users still locally have the same limitation as https://studio.asyncapi.com/ - no support in web app for references pointing to the local file system.

I think we need new command: asyncapi start preview

• it can still use studio
• it would have to take a AsyncAPI file before starting studio and bundle local references )using the same mechanism as asyncapi bundle) and do it in memory (not save to file) and pass to studio
• studio would have to be started with readOnly=true param to hide editor (it has some limits though readOnly Query Parameter not hiding text editor studio#591)

And the preview would have to be hot reloaded on any change in the file on local

example with local file reference: https://www.asyncapi.com/docs/tutorials/kafka/configure-kafka-avro#reusing-existing-avro-schemas

How will this change help?

Solve problem that to preview my local AsyncAPI document on local, that uses local file references, I need to generate docs or use special plugins.

Screenshots

No response

How could it be implemented/designed?

already described in main description.

although maybe instead of using studio better just use react component directly? 🤔 something to validate during implementation. This is how preview was done in https://github.com/asyncapi/vs-asyncapi-preview

🚧 Breaking changes

No

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

No, someone else can work on it.

[GauravSaini01]

I am working on this.

[Paribesh01]

@derberg The readOnly parameter cannot be used with locally stored files; it must be used with a URL. So, when starting this
new command with a local file, the readOnly mode will not work.

[derberg]

yes, readOnly works with URL only:

• that could be improved in https://github.com/asyncapi/studio
• or we could start a tiny server to host the preview file, and use url query param on studio to point to localhost. We already for example start a websocket for asyncapi start studio command

what I'm thinking about is - should we use studio, or maybe better use https://github.com/asyncapi/asyncapi-react (used in studio for preview) directly. It is super simple to use like https://github.com/asyncapi/asyncapi-react/blob/master/docs/usage/web-component.md

I would say requirement is:

• asyncapi start preview should work like any other command in CLI (no -f flag for file reference like it is done in asyncapi start studio is not consistent with other commands #1623)
• from above options pick solution that will work the best with functionality to have hot reload of preview, to see new changes showing up in preview real-time

if the best solution is to first do some improvements in studio - do not reject such solution and simply make improvement in studio first

[Shurtu-gal]

Just my two cents here, can't we put this as an additional feature in studio. Because having two commands do the same thing doesn't sit right with me somehow?

[derberg]

but these are 2 separate things imho, one is to open studio, and studio is a tool for AsyncAPI editing. The other is only to open the preview, like the VSCode extension, when you see a human readable documentation generated on the side of editing your AsyncAPI document in IDE, not Studio (as you want local file references to work).

of course, as I said, it can be a feature in Studio (that is almost there but support url query param only), but asyncapi start preview should be individual command as imho it has intuitive name and is just simple to use, no need to undestand what studio is.

[Shurtu-gal]

Fair enough.

If we are making it readonly, should we just use asyncapi/react to render a component or do we want navigation and other cool stuff?

[derberg]

no strong opinion, I wrote above that using react directly is also technically possible. Up to you. I would choose solution that is easiest to implement, and I think reusing studio is the easiest as there is already a solution for websocket connection to support reload