Vue JSX Prop Merging Helper

Common errors

• TypeError: _mergeJSXProps is not a function

  cause This error typically indicates that a Babel transformation or build tool is attempting to import `_mergeJSXProps` as a default export, but the package either doesn't provide one or it's being resolved incorrectly. This was a known issue in older setups.
  fix Verify that your Babel configuration (e.g., `babel.config.js`) for Vue JSX is correctly set up using `@vue/babel-preset-jsx` and that your build tools are resolving modules correctly. This package is an internal helper, and direct `import` statements for `_mergeJSXProps` in user code are not expected.

• Error: Plugin 'transform-vue-jsx' cannot be used with Vue 3. Please use '@vue/babel-plugin-jsx' instead.

  cause You are attempting to use the Vue 2.x JSX transformation pipeline (which relies on this helper) in a Vue 3 project.
  fix Update your Babel configuration to use `@vue/babel-plugin-jsx` for Vue 3 projects. This package and its direct consumers (`@vue/babel-preset-jsx`, `@vue/babel-plugin-transform-vue-jsx`) are not compatible with Vue 3.

• Cannot find module 'babel-helper-vue-jsx-merge-props' or its corresponding type declarations.

  cause The package is either not installed, or there's an issue with module resolution in your build environment. If seen during a Babel transformation, it indicates the plugin consuming it cannot locate the helper.
  fix Ensure the package is installed as a dependency (`npm install babel-helper-vue-jsx-merge-props` or `yarn add babel-helper-vue-jsx-merge-props`). If this occurs during a build and you're using `@vue/babel-preset-jsx`, ensure all related Vue JSX Babel packages are correctly installed.

Warnings

• gotcha This package is an internal Babel helper and is not designed for direct consumption by end-user applications. Attempting to directly import or use its exports in your application code is discouraged and may lead to unexpected behavior or build errors.
  Fix: Ensure you are using `@vue/babel-preset-jsx` or `@vue/babel-plugin-transform-vue-jsx` (for Vue 2) to handle JSX transformations, which will utilize this helper internally.
• breaking This helper is specifically for Vue 2.x JSX transformations. For Vue 3.x applications, you should use `@vue/babel-plugin-jsx` instead, as Vue 3's render function and VNode structure are different, requiring a different JSX transformation approach.
  Fix: For Vue 3 projects, configure Babel to use `@vue/babel-plugin-jsx`. Remove `@vue/babel-preset-jsx` or `@vue/babel-plugin-transform-vue-jsx` and their dependencies if targeting Vue 3.
• gotcha This package requires Babel 7.x or higher to function correctly. Using it with older Babel versions (e.g., Babel 6) will result in incompatibility issues and build failures.
  Fix: Upgrade your project's Babel dependencies to Babel 7+ to ensure compatibility.
• gotcha Past versions of this package were reported to lack a default export, leading to build errors when tools attempted `import _mergeJSXProps from 'babel-helper-vue-jsx-merge-props'`. While typically handled by the consuming Babel plugin, this could surface as a build issue in specific toolchain configurations.
  Fix: Ensure your Babel setup for Vue JSX is correctly configured, ideally using `@vue/babel-preset-jsx`. If manually configuring plugins, verify that the `_mergeJSXProps` helper is referenced correctly (e.g., via `require` or named import if applicable) by the plugin using it, rather than expecting a default export.
• gotcha When using JSX with TypeScript in Vue CLI, appending `@vue/babel-preset-jsx` to presets may introduce errors due to duplication, as `@vue/cli-plugin-babel/preset` already includes it.
  Fix: If using Vue CLI, remove redundant `@vue/babel-preset-jsx` entries in `babel.config.js`. Use `<script lang="tsx">` in SFCs to ensure proper TypeScript parsing for JSX.

Install

• npm install babel-helper-vue-jsx-merge-props npm
• yarn add babel-helper-vue-jsx-merge-props yarn
• pnpm add babel-helper-vue-jsx-merge-props pnpm

Imports

• _mergeJSXProps
  wrong:

  import _mergeJSXProps from 'babel-helper-vue-jsx-merge-props';

  correct:

  /* This package is not intended for direct import by end-users. It is internally imported by Babel plugins. */

  This package is an internal Babel helper and does not expose a public API for direct import and usage by application code. Previous versions sometimes caused issues when build tools attempted a default import, as it historically lacked one.

Quickstart

Illustrates Babel configuration for Vue 2 JSX, showing how this helper enables prop spreading within components, without direct code usage.

/*
This package is an internal Babel helper and is not directly used in application code.
Instead, it is a dependency of Babel plugins/presets that enable Vue JSX.
Below is an example of how you would configure Babel to enable Vue 2 JSX support,
which implicitly uses this helper for prop merging.
*/

// babel.config.js
module.exports = {
  presets: [
    // For Vue 2.x projects using JSX
    ['@vue/babel-preset-jsx', { /* options, e.g., 'compositionAPI': true for Vue 2.7 */ }]
    // For Vue 3.x, use '@vue/babel-plugin-jsx' instead, which has its own merge logic.
  ]
};

// MyComponent.vue (example using JSX with prop spreading)
<script lang="jsx">
import Vue from 'vue';

export default Vue.extend({
  props: {
    baseProps: { type: Object, default: () => ({}) },
    extraClass: { type: String, default: '' },
  },
  render() {
    const mergedProps = { class: `my-component ${this.extraClass}`, ...this.baseProps };
    return (
      <div
        {...mergedProps}
        onClick={() => console.log('Component clicked with merged props.')}
      >
        Hello from JSX Component!
      </div>
    );
  },
});
</script>