Community - Development setup

This guide helps you set up the generator locally and run it. For testing, see Testing. For releasing, see Release process. For the AI tools that review your PRs, see AI tooling.

Before you begin - new contributor onboarding

New to AsyncAPI Generator? We strongly recommend watching our comprehensive onboarding webinar first:

Watch: One Tool, One Flow: AsyncAPI's New Take on Code/Docs/Config Generation

What you'll learn:

• What AsyncAPI is and the challenges it solves
• The origins and evolution of the Generator (legacy vs. future architecture)
• Understanding event-driven architectures and protocol complexity
• How the Generator works: templates, render engines, and the generation process
• Component-based template development for better reusability
• Baked-in templates and the monorepo structure
• Live demonstrations of code generation from AsyncAPI documents

This webinar provides essential context about the Generator's architecture, design decisions, and development workflow. Watching it will make the rest of this development guide much clearer and help you contribute more effectively.

Getting started

1. Fork & Clone the repository:

First fork the repository from GitHub and then clone it using the following command:

1git clone https://github.com/{your_username}/generator.git
2cd generator

After cloning the repository, you should set up the fork properly and configure the remote repository as described in the AsyncAPI git workflow guidelines.

2. Install dependencies:

npm install --workspaces

CLAUDE.md vs AGENTS.md: The repo may ship CLAUDE.md as a symlink to AGENTS.md (the canonical guidelines file). After cloning, Linux and macOS usually need no extra step. On Windows, turn on Developer Mode (or enable symlink permissions), run git config core.symlinks true, then git checkout -- CLAUDE.md so Git creates a real symlink and not a one-line text stub. Edit AGENTS.md only for content updates and the symlink follows automatically.

Additional commands

• Lint the code: npm run lint
• Generate documentation: npm run docs
• Build Docker image: npm run docker:build

Troubleshooting

If you encounter any issues during development or testing, please check the following:

1. Ensure you're using the correct Node.js version (24.11 or higher) and npm version (11.5.1 or higher).
2. Clear the node_modules directory and reinstall dependencies if you encounter unexpected behavior.
3. For Docker-related issues, make sure Docker is running and you have sufficient permissions.

If problems persist, please open an issue on the GitHub repository.