generator How can we trigger generation of local templates as build in templates and not npm packages (MVP)

lots of work and unknown here.

might be some breaking change 🤔

but basically the goal is to figure out how we can:

include all templates from https://github.com/asyncapi/generator/tree/master/packages in the @asyncapi/generator
how to make generator "aware" of these templates, so there is no need to fetch from NPM/GitHub
what changes in docs will be needed? do we need to change some concepts? like templates from remote and templates that are incluced in generator? core templates

So when for example CLI uses Generator, it has access to API that give info about what templates are available, what languages they support and what kind of output (like client or maybe docs)

basically make this vision come true: https://www.linkedin.com/posts/lukasz-gornicki-a621914_this-is-on-my-wishlist-for-asyncapi-generator-activity-7275794977744433152-ZrTK?utm_source=share&utm_medium=member_desktop&rcm=ACoAAAC88aoBtJebjfqQZ-iTK5AuS7Ceb8yntWc

We need to finally get this solved so we can also start moving repos from outside to generator, like for example html-template

Jun 16 '25 12:06 derberg

Bounty Issue's service comment

Text labels: bounty/2025-Q3, bounty/advanced, bounty/coding First assignment to regular contributors: 2025-06-20 00:00:00 UTC+12:00 End Of Life after: 2025-07-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

The Bounty Program is not a Mentorship Program. The accepted level of Bounty Program Participants is Middle/Senior.

Regular contributors should explain in meaningful words how they are going to approach the resolution process when expressing a desire to work on this Bounty Issue.

Jun 16 '25 13:06 aeworxet

Hi @derberg

I'd like to take up this issue as part of the bounty program.

Here's how I plan to approach it:

Identify and move all relevant templates from /packages into a structured /core-templates directory inside the generator.
Update the generator's internal logic to detect, register, and expose these templates (language, type, metadata).
Ensure the CLI/API exposes these templates cleanly and supports legacy remote template loading for backward compatibility.
Update documentation to differentiate clearly between core (local) and external (remote) templates.

This will bring us closer to the vision of having built-in, discoverable templates without requiring NPM or GitHub fetches

Looking forward to getting started!
Please assign the issue to me when the bounty window opens

Thanks!

Note : I don't know i can work on bounty issues or not , if yes please help me to achieve this.

Jun 16 '25 17:06 rohithyarramala

@rohithyarramala I'll be working on it. It is a complex task and requires a lot of experience with generator

Jun 18 '25 09:06 derberg

oh, ok @derberg, if any help is needed for it, I can be helpful, not for bounty. for the experience.

Jun 18 '25 09:06 rohithyarramala

Following the expression of desire to work on this Bounty Issue, @derberg (githubID: 6995927) is an AsyncAPI Maintainer specified in the file https://github.com/asyncapi/community/blob/master/MAINTAINERS.yaml, so they fall under the first category in the prioritization list.

Jun 18 '25 12:06 aeworxet

Bounty Issue's Timeline

Complexity Level	Assignment Date (by GitHub)	Start Date (by BP Rules)	End Date (by BP Rules)	Draft PR Submission	Final PR Merge Start	Final PR Merge End
Advanced	2025-06-18	2025-07-07	2025-08-31	2025-07-27	2025-08-17	2025-08-31

Please note that the dates given represent deadlines, not specific dates; so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

Assignee: @derberg (githubID: 6995927)

Jun 18 '25 12:06 aeworxet

Template name pattern

First of all templates name would have special pattern. Example template name: @asyncapi/core-template-client-websocket-python or @asyncapi/core-template-client-websocket-java-quarkus or @asyncapi/core-template-docs-html or @asyncapi/core-template-docs-markdown

@asyncapi a typical scope name for official AsyncAPI packages
core to indicate it is template that is already included in generator, developed under monorepo
template yeah, pretty obvious 😄
client or docs that reflects also our file structure in packages dir, first we define what is the type of the template
templates other than docs will have one category more called protocol like websocket or kafka
java or markdown so language/standard/syntax used
spring or express to indicate if some special framework is used as there might be different flavours of the template for different languages

Template metadata location

We would keep it under ageneratorrc file. We already have supportedProtocols but would mark it as deprecated and instead have:

metadata:
    # could be docs|config
    type: client
    # if not provided that it means any protocol
    protocol: kafka
    # not language as can also be html or markdown or yaml
    target: java
    # not framework as it could also be helm for example
    stack: quarkus

How we connect core templates with generator?

each template is added as dependency to generator
we have a build script that travers all "core templates" dependencies provided in package.json and read their ageneratorrc and outputs a template-list file like:

[
  {
    "name": "@asyncapi/core-template-client-websocket-java-quarkus",
    "path": "node_modules/@asyncapi/core-template-client-websocket-java-quarkus",
    "type": "client",
    "stack": "quarkus",
    "protocol": "websocket",
    "target": "java"
  },
  {
    "name": "@asyncapi/core-template-docs-html",
    "path": "node_modules/@asyncapi/core-template-docs-html",
    "type": "docs",
    "target": "html"
  }
]

such a config is shipped with generator

New function in generator

We would need a new function like listTemplates that anyone could use, like AsyncAPI CLI, but not only to get a list of what core templates are available.

// ------------------------------
// Function implementation
// ------------------------------
const templates = require('./the_build_generated_templates_list');

function listTemplates({ type, stack, protocol, target }) {

  return templates.filter(t =>
    (!type || t.type === type) &&
    (!stack || t.stack === stack) &&
    (!protocol || t.protocol === protocol) &&
    (!target || t.target === target)
  );
}

// ------------------------------
// Example usage
// ------------------------------
console.log("All templates");
console.table(
  listTemplates()
);

console.log("Java + Quarkus templates no matter if client or not");
console.table(
  listTemplates({ target: 'java', stack: 'quarkus' })
);

console.log("HTML docs");
console.table(
  listTemplates({ target: 'html', type: 'docs' })
);

Changes in generator

a bit of refactoring of installation functions (will move the out from generator.js)

  async installAndSetupTemplate() {

    // simple code that will basically first identify if core template name is passed, template from config list
    // then skip npm installation as it is not needed as template is already in the node_modules and we have path to it in config
    const { name: templatePkgName, path: templatePkgPath } = await this.installTemplate(this.install);
    this.templateDir = templatePkgPath;
    this.templateName = templatePkgName;
    this.templateContentDir = path.resolve(this.templateDir, TEMPLATE_CONTENT_DIRNAME);

    await this.loadTemplateConfig();

    return { templatePkgName, templatePkgPath };
  }

Versioning of core templates and generator is unified into one

Still not 100% sure what are the negative outcomes of that decision

Jul 16 '25 12:07 derberg

that's just drop of ideas, still thinking before I do mvp

Jul 16 '25 12:07 derberg

still don't know if we need to do something with generator: ">=1.3.0 <3.0.0". Probably make it optional is enough, and not using it in baked-in templates

Jul 16 '25 14:07 derberg

presented in https://fathom.video/share/4nzzKDCGYzboS3XUL5xe4b8a7VxYeVuM

Jul 16 '25 14:07 derberg

@derberg (githubID: 6995927), please provide an update to the PR of the Bounty Issue.

Aug 11 '25 22:08 aeworxet

completed, instead of MVP https://github.com/asyncapi/generator/pull/1648 actually released v2.8 with new feature in it

Aug 25 '25 06:08 derberg

Bounty Issue Is Completed 🎉

@derberg (githubID: 6995927), please go to the dedicated AsyncAPI Bounty Program 2025-Q3 page on Open Collective and submit an invoice for USD 400.00 (button 'ACTIONS', dropdown option 'Submit expense') with the expense title Bounty generator#1614, tag bounty, and full URL of this Bounty Issue in the description.

After submitting the invoice, please post the link to it in this Bounty Issue as a separate comment to verify the invoice's authorship.

Aug 25 '25 10:08 aeworxet

https://opencollective.com/asyncapi/projects/asyncapi-bounty-program/expenses/262764

Aug 26 '25 06:08 derberg

derberg https://opencollective.com/asyncapi/projects/asyncapi-bounty-program/expenses/262764

✅ The invoice https://opencollective.com/asyncapi/projects/asyncapi-bounty-program/expenses/262764 was submitted by @derberg (githubID: 6995927), who was the AsyncAPI Bounty Program 2025-Q3 Participant and completed the Bounty Issue generator#1614.

Aug 26 '25 07:08 aeworxet