Diagnosing Babel Class Properties Transpilation Failures

Problem: Babel Skips Class Property Syntax

In a recent build you notice that class fields like static foo = 1 or instance properties defined with an initializer are missing from the output. The JavaScript runs in a browser that should support them, but the transpiler has left the original syntax untouched, causing a SyntaxError: Unexpected token at runtime.

Why It Happens

Babel 7+ requires the @babel/plugin-proposal-class-properties plugin to transform class fields. Even with the plugin installed, a few misconfigurations can prevent the transformation:

• Plugin absent from plugins array.
• Plugin listed before @babel/preset‑env, so it gets skipped by the preset’s targets filter.
• Targets in preset‑env do not include environments that support class fields (e.g., es2019 missing).
• Build tool cache still holds old Babel output.

Diagnostic Checklist

1. Verify Babel Configuration
   • Run cat babel.config.js or cat .babelrc.
   • Confirm @babel/plugin-proposal-class-properties appears under plugins.
   • Example snippet:

     module.exports = {
       presets: [
         ['@babel/preset-env', { targets: { esmodules: true } }]
       ],
       plugins: ['@babel/plugin-proposal-class-properties']
     };
     

2. Check Plugin Order
   • Babel applies presets first, then plugins. Ensure the plugin comes after the preset.
   • Misordered config example:

     plugins: ['@babel/plugin-proposal-class-properties'],
     presets: ['@babel/preset-env']
     

3. Inspect Target Environments
   • Run npx browserslist to view the resolved list.
   • Make sure es2019 or equivalent is present; otherwise, class fields may be considered unsupported.
   • Adjust targets in preset‑env if needed.
4. Clear Build Tool Cache
   • Webpack: rm -rf node_modules/.cache.
   • Rollup: delete the dist folder or any caching directories.
5. Re‑run Babel Directly
   • Execute npx babel src --out-dir lib --source-maps.
   • Open a generated file and search for classFields or the original field syntax.
6. Validate Runtime
   • Serve lib and open the console. No syntax errors should appear.

Common Fixes and Their Impact

• Add the Plugin
  • Install: npm i -D @babel/plugin-proposal-class-properties.
  • Benefit: Enables transformation of class fields.
  • Risk: Increases bundle size slightly due to added helper code.
• Reorder Plugins
  • Place all plugins after the last preset.
  • Benefit: Ensures the plugin runs when the preset deems the target environment supports the feature.
  • Risk: If another plugin depends on a preset‑generated AST, moving it might break that transform.
• Adjust Targets
  • Update preset‑env to include es2019 or a specific browser list.
  • Benefit: Prevents Babel from skipping the plugin.
  • Risk: May cause other polyfills to be omitted if the target list is too narrow.
• Clear Cache
  • Benefit: Removes stale compiled files that might still contain the original syntax.
  • Risk: Minor build time increase during the next run.

Escalation Criteria

1. If after applying all fixes the output still contains class field syntax, verify that the Babel CLI is using the correct config file. Run npx babel --config-file path/to/babel.config.js to force the file.
2. If the plugin is present but Babel still skips it, check for babel-plugin-transform-runtime or other runtime helpers that might override plugin behavior.
3. Inspect babel-loader or rollup-plugin-babel options in your bundler config; ensure they reference the same config file and that cacheDirectory is not misconfigured.
4. As a last resort, isolate the issue by creating a minimal project that only contains a class with a property. If the minimal setup works, the problem lies in a conflicting plugin or preset in the original project.

Practical Verification Checklist

Check	Command / Action	Expected Result
Config file contains plugin	grep -R "class-properties" -n .babelrc babel.config.js	Line showing the plugin
Plugin after preset	Inspect order in file	Preset listed before plugin
Target list includes es2019	npx browserslist	List contains es2019 or equivalent
Cache cleared	rm -rf node_modules/.cache	No cache folder left
Generated code contains no class fields	Open output file	No static foo syntax present

Limitations and Caveats

• Older projects may rely on the legacy transform-class-properties plugin; migrating to the new proposal plugin can change the output.
• Using @babel/preset‑react can add its own plugin order; ensure class property support remains after merging presets.
• When targeting Node.js, the targets field must match the Node version; otherwise, Babel may skip the transform.

Conclusion

Class property transpilation failures usually boil down to a missing plugin, wrong order, inadequate targets, or stale cache. By following the ordered checks above, you can quickly pinpoint the root cause and apply a minimal fix. If the issue persists after escalation steps, consider creating a minimal repro and consulting the Babel GitHub issues for similar patterns.