Switch to ESM (#1726)

* Add Jest tests for importing/requiring react-on-rails

* Update attw

* Ship ESM build

* Test type: module

* Add extensions to imports

* Remove module/moduleResolution again

* Fix ReactDOM build errors

* Move require into .cts

* Fix Jest config

* Add changelog and release notes

* Import ReactDOMServer from reactApis instead of directly

* Improve react-dom handling

* Optimize react-dom/server bundle size

* Move react-dom/server reexports to a separate file

* Switch to fully undeprecated ts-jest config

* Deduplicate spec/dummy dependencies

---------

Co-authored-by: Alexey Romanov <alexey.v.romanov@gmail.com>
Co-authored-by: Roman Kuksin <roman@shakacode.com>

Author: 3 people

.github/workflows/lint-js-and-ruby.yml

@@ -89,10 +89,8 @@ jobs:
       - name: Pack for attw and publint
         run: yarn pack -f react-on-rails.tgz
       - name: Lint package types
-        # --profile because we don't care about node10
-        # --ignore-rules CJS default export can't be resolved at the moment,
-        # revisit in 15.0.0
-        run: yarn run attw react-on-rails.tgz --profile node16 --ignore-rules cjs-only-exports-default
+        # our package is ESM-only
+        run: yarn run attw react-on-rails.tgz --profile esm-only
       - name: Lint package publishing
         run: yarn run publint --strict react-on-rails.tgz
       # We only download and run Actionlint if there is any difference in GitHub Action workflows

.github/workflows/main.yml

@@ -154,6 +154,10 @@ jobs:
         run: cd spec/dummy && yalc add react-on-rails
       - name: Install Node modules with Yarn for dummy app
         run: cd spec/dummy && yarn install --no-progress --no-emoji
+      - name: Dummy JS tests
+        run: |
+          cd spec/dummy
+          yarn run test:js
       - name: Install Ruby Gems for package
         run: |
           bundle lock --add-platform 'x86_64-linux'

CHANGELOG.md

@@ -35,6 +35,7 @@ Changes since the last non-beta release.
 
 ### Changed
 
+- **Breaking change**: The package is ESM-only now. Please see [Release Notes](docs/release-notes/15.0.0.md#esm-only-package) for more details.
 - The global context is now accessed using `globalThis`. [PR 1727](https://github.com/shakacode/react_on_rails/pull/1727) by [alexeyr-ci2](https://github.com/alexeyr-ci2).
 - Generated client packs now import from `react-on-rails/client` instead of `react-on-rails`. [PR 1706](https://github.com/shakacode/react_on_rails/pull/1706) by [alexeyr-ci](https://github.com/alexeyr-ci).
   - The "optimization opportunity" message when importing the server-side `react-on-rails` instead of `react-on-rails/client` in browsers is now a warning for two reasons:

docs/release-notes/15.0.0.md

@@ -68,6 +68,15 @@ Major improvements to component and store hydration:
 - If you were previously using `defer_generated_component_packs: false`, use `generated_component_packs_loading_strategy: :sync` instead
 - For optimal performance with Shakapacker ≥ 8.2.0, consider using `generated_component_packs_loading_strategy: :async`
 
+### ESM-only package
+
+The package is now published as ES Modules instead of CommonJS. In most cases it shouldn't affect your code, as bundlers will be able to handle it. However:
+
+- If you explicitly use `require('react-on-rails')`, and can't change to `import`, upgrade to Node v20.19.0+ or v22.12.0+. They allow `require` for ESM modules without any flags. Node v20.17.0+ with `--experimental-require-module` should work as well.
+- If you run into `TS1479: The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require'.` TypeScript error, you'll need to [upgrade to TypeScript 5.8 and set `module` to `nodenext`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-8.html#support-for-require-of-ecmascript-modules-in---module-nodenext).
+
+Finally, if everything else fails, please contact us and we'll help you upgrade or release a dual ESM-CJS version.
+
 ### `globalThis`
 
 [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) is now used in code.

eslint.config.ts

@@ -133,6 +133,12 @@ const config = tsEslint.config([
       'jsx-a11y/anchor-is-valid': 'off',
     },
   },
+  {
+    files: ['node_package/**/*'],
+    rules: {
+      'import/extensions': ['error', 'ignorePackages'],
+    },
+  },
   {
     files: ['lib/generators/react_on_rails/templates/**/*'],
     rules: {
@@ -143,7 +149,7 @@ const config = tsEslint.config([
     },
   },
   {
-    files: ['**/*.ts', '**/*.tsx'],
+    files: ['**/*.ts{x,}', '**/*.[cm]ts'],
 
     extends: tsEslint.configs.strictTypeChecked,
 

jest.config.js

@@ -1,7 +1,17 @@
+import { createJsWithTsPreset } from 'ts-jest';
+
 const nodeVersion = parseInt(process.version.slice(1), 10);
 
-module.exports = {
-  preset: 'ts-jest/presets/js-with-ts',
+export default {
+  ...createJsWithTsPreset({
+    tsconfig: {
+      // Relative imports in our TS code include `.ts` extensions.
+      // When compiling the package, TS rewrites them to `.js`,
+      // but ts-jest runs on the original code where the `.js` files don't exist,
+      // so this setting needs to be disabled here.
+      rewriteRelativeImportExtensions: false,
+    },
+  }),
   testEnvironment: 'jsdom',
   setupFiles: ['<rootDir>/node_package/tests/jest.setup.js'],
   // React Server Components tests are compatible with React 19

node_package/src/Authenticity.ts

@@ -1,4 +1,4 @@
-import type { AuthenticityHeaders } from './types/index';
+import type { AuthenticityHeaders } from './types/index.ts';
 
 export function authenticityToken(): string | null {
   const token = document.querySelector('meta[name="csrf-token"]');

node_package/src/CallbackRegistry.ts

@@ -1,6 +1,6 @@
-import { ItemRegistrationCallback } from './types';
-import { onPageLoaded, onPageUnloaded } from './pageLifecycle';
-import { getRailsContext } from './context';
+import { ItemRegistrationCallback } from './types/index.ts';
+import { onPageLoaded, onPageUnloaded } from './pageLifecycle.ts';
+import { getRailsContext } from './context.ts';
 
 /**
  * Represents information about a registered item including its value,

node_package/src/ClientSideRenderer.ts

@@ -1,18 +1,16 @@
 /* eslint-disable max-classes-per-file */
-/* eslint-disable react/no-deprecated,@typescript-eslint/no-deprecated -- while we need to support React 16 */
 
-import * as ReactDOM from 'react-dom';
 import type { ReactElement } from 'react';
-import type { RailsContext, RegisteredComponent, RenderFunction, Root } from './types';
+import type { RailsContext, RegisteredComponent, RenderFunction, Root } from './types/index.ts';
 
-import { getRailsContext, resetRailsContext } from './context';
-import createReactOutput from './createReactOutput';
-import { isServerRenderHash } from './isServerRenderResult';
-import reactHydrateOrRender from './reactHydrateOrRender';
-import { supportsRootApi } from './reactApis';
-import { debugTurbolinks } from './turbolinksUtils';
-import * as StoreRegistry from './StoreRegistry';
-import * as ComponentRegistry from './ComponentRegistry';
+import { getRailsContext, resetRailsContext } from './context.ts';
+import createReactOutput from './createReactOutput.ts';
+import { isServerRenderHash } from './isServerRenderResult.ts';
+import { supportsHydrate, supportsRootApi, unmountComponentAtNode } from './reactApis.cts';
+import reactHydrateOrRender from './reactHydrateOrRender.ts';
+import { debugTurbolinks } from './turbolinksUtils.ts';
+import * as StoreRegistry from './StoreRegistry.ts';
+import * as ComponentRegistry from './ComponentRegistry.ts';
 
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
 
@@ -103,8 +101,7 @@ class ComponentRenderer {
         }
 
         // Hydrate if available and was server rendered
-        // @ts-expect-error potentially present if React 18 or greater
-        const shouldHydrate = !!(ReactDOM.hydrate || ReactDOM.hydrateRoot) && !!domNode.innerHTML;
+        const shouldHydrate = supportsHydrate && !!domNode.innerHTML;
 
         const reactElementOrRouterResult = createReactOutput({
           componentObj,
@@ -156,7 +153,8 @@ You should return a React.Component always for the client side entry point.`);
       }
 
       try {
-        ReactDOM.unmountComponentAtNode(domNode);
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        unmountComponentAtNode(domNode);
       } catch (e: unknown) {
         const error = e instanceof Error ? e : new Error('Unknown error');
         console.info(

node_package/src/ComponentRegistry.ts

@@ -1,6 +1,6 @@
-import { type RegisteredComponent, type ReactComponentOrRenderFunction } from './types';
-import isRenderFunction from './isRenderFunction';
-import CallbackRegistry from './CallbackRegistry';
+import { type RegisteredComponent, type ReactComponentOrRenderFunction } from './types/index.ts';
+import isRenderFunction from './isRenderFunction.ts';
+import CallbackRegistry from './CallbackRegistry.ts';
 
 const componentRegistry = new CallbackRegistry<RegisteredComponent>('component');