Migrate Component

Migrate Component to @asyncapi/generator-components

You are migrating a duplicated React/JSX template-local component out of packages/templates/clients/<protocol>/<lang>[/<framework>]/components/ (the <framework> segment is present for stack-specific templates like java/quarkus, omitted for single-stack languages like python) into the shared packages/components/src/components/ package.

Important: Always edit src/ files. The lib/ directory is generated at publish time by Babel — never edit files there.

Invocation

The user has named the component to migrate, e.g. "migrate HandleError". If they did NOT name one, ask which component.

Preconditions (fast gate)

1. Two-template threshold check

Use the Glob tool with pattern packages/templates/clients/**/components/<Component>.js to find all template-local copies of this component.

Decide based on the result count:

The 1-template case is the only judgment call — do not stop unilaterally; let the user make the call.

2. No naming collision

Use the Glob tool with pattern packages/components/src/components/<Component>.js — if it returns a result, stop and report that the component already exists in the shared package.

Research & design (produce the migration plan)

Before touching any files, work through these three steps in order. Each produces an artifact the execution steps consume directly:

1. The template files — the canonical list of files to migrate from templates into the shared package.
2. The props table — file × props × render-shape × indent/newLines.
3. The union signature — the shared component's prop list, with required/optional/defaults.

1. Catalog the template files

The Glob results from precondition 1 are the canonical list — call it "the template files" in subsequent steps. Every later step (read sources, delete files, update imports) refers back to these exact paths. Echo the list back to the user as a fenced block so it stays visible; do not re-run Glob.

2. Read every copy and tabulate

Read every path in the template files — one read per file, no skipping. For each, record one row in a markdown table:

This table is the source of truth for the next two research steps. Print it back to the user.

3. Derive the prop signature (union rule)

The shared component's props are the union of props across the template files:

• Prop in every template file → required (no default).
• Prop in some template files → optional, with a default matching the omitting file's current behavior.
• Prop with different defaults per language → keep required; push the per-language value into the consuming template's JSX usage.

Worked example (using the table above):

// Per-copy props:
//   javascript → { methodName, methodParams = ['msg'] }
//   python     → { methodName, methodParams = ['self','msg'], preExecutionCode }
//   dart       → { methodName }
//
// Union → { methodName, methodParams, preExecutionCode }
//   methodName       → required          (in every copy)
//   methodParams     → optional, ['msg'] (JS/Dart omit; Python overrides at the call site)
//   preExecutionCode → optional, ''      (only Python uses it; default is a no-op for JS/Dart)

export function <Component>({
  methodName,
  methodParams = ['msg'],
  preExecutionCode = '',
}) { /* … */ }

Python's consuming template then renders <<Component> methodName='onMessage' methodParams={['self','msg']} preExecutionCode='…' />; JS/Dart pass only what they need.

Choose the abstraction shape based on the table and signature:

• Method-shaped — delegates to MethodGenerator with a websocket<X>Config map. Use when per-language differences are mostly method-body strings (the config object holds the language-specific logic; the component itself is thin). See packages/components/src/components/RegisterErrorHandler.js.
• Structural — config object keyed by language returning Text code blocks. Use when the rendering structure itself varies across languages (different indentation, different block shapes, framework sub-keys). See packages/components/src/components/QueryParamsVariables.js.

Execution steps

Execute strictly in this order; each step must succeed before the next.

1. Author the shared component

Create packages/components/src/components/<Component>.js using the signature and abstraction shape from research step 3.

Two things to enforce (everything else — named export, body code, imports, EOF newline — copy from the canonical example for your chosen shape):

• JSDoc — @typedef for the Language union, @param for every prop in the research step 3 union (matching required/optional/defaults exactly), @returns {JSX.Element}, and a @example block. This is what jsdoc2md publishes to apps/generator/docs/api_components.md in step 9; missing or malformed tags produce an empty diff there.
• Validate constrained props — for language/framework (or any prop with a supported set), throw using helpers from packages/components/src/utils/ErrorHandling.js. Use unsupportedLanguage(language, supportedList) for the language prop; use unsupportedFramework(language, framework, supportedList) when the component also accepts a framework prop (e.g. java/quarkus). See QueryParamsVariables.js for the full pattern.

2. Export it

Edit packages/components/src/index.js: append one line export { <Component> } from './components/<Component>';.