babel-plugin-jsx-map-class-props v1.0.0

babel-plugin-jsx-map-class-props

Merges class names from any attribute with className or other compatible attributes.

• Installation
• Why?
• Configuration
  • Options
  • Attribute Mapping Options
  • Allowed combination of source-target options
• How does it work?
• Runtime attribute value formatting and merging
• Have a question or want to suggest an improvement?

Installation

When babel-plugin-jsx-map-class-props cannot resolve attribute value at compile time, it imports helper functions (read Runtime attribute value formatting and merging). Therefore, you must install babel-plugin-jsx-map-class-props as a direct dependency of the project.

npm install babel-plugin-jsx-map-class-props --save

Why?

The idea was born when I tried to identify the components in our E2E tests. First of all I tried to find a property that most components pass to the DOM. I read about testId, data-test-id and some others, but our components library isn't aware of any of them. Then I thought about className. It is supported by most components. But we use CSS-modules, which decorates the class names, and so they cannot be simply recognized by e2e test. So we have to use additional classes for tests and combine them with the existing ones, and that makes a mess. Also we need to strip them in production. Finally, the combination of both directions gave me a new idea: i could put an identifier into a different property and merge it with the className at compile time. It also solved the issue of stripping these properties for production.

Configuration

Configure the options for the plugin within your .babelrc as follows:

{
  "plugins": [
    ["jsx-map-class-props", {
      "option": "value"
    }]
  ]
}

Options

Attribute Mapping Options

Missing a configuration? Raise an issue.

Allowed combinations of source-target options

(in priority order)

Notes:

• only one combination per mapping is allowed
• other options will be ignored (according to priority)
• if attribute is matched by a mapping, other mappings are ignored (in other words, an attribute can have only one target)

How does it work?

1. Iterates through all JSX element declarations.
2. Finds matched source attributes according to the mapping options.
   • If clean option is true, removes the source attribute that was found from the element and continues to the next iteration.
3. Calculates target attribute names according to the mapping options.
4. Formats source attribute value according to the mapping options:
   • If value is a string literal, generates a string literal value.
   • If value is a jSXExpressionContainer and format option is valid, uses a helper function (getClassName) to format value at runtime.
5. Merges source attribute value with the target attribute:
   • If target attribute doesn't exist, moves formatted source attribute to the target.
   • If source and target values are a string literal, generates a string literal value.
   • If source or target value is a jSXExpressionContainer, uses a helper function (joinClassNames) to join values at runtime.
6. Removes the source attribute from the element.

Runtime attribute value formatting and merging

When the value of a source attribute cannot be determined at compile time, babel-plugin-jsx-map-class-props uses getClassName helper function to format the value at runtime.

Input:

<div test-className={Math.random() > .5 ? 'a' : 'b'} />;

Output:

import _getClassName from 'babel-plugin-jsx-map-class-props/dist/browser/getClassName';

<div className={
  _getClassName(Math.random() > .5 ? 'a' : 'b', 'e2e-|')
} />;

When the value of a source or a target attribute cannot be determined at compile time, babel-plugin-jsx-map-class-props uses joinClassNames helper function to join the values at runtime.

Input:

<div test-className='my-component' className={styles.myComponent} />;

Output:

import _joinClassNames from 'babel-plugin-jsx-map-class-props/dist/browser/joinClassNames';

<div className={
  _joinClassNames('e2e-my-component', styles.myComponent)
} />;

Have a question or want to suggest an improvement?

• Have technical questions? Ask on Stack Overflow.
• Have a feature suggestion or want to report an issue? Raise an issues.