Migrate Cropper to Hooks and React Compiler

[ValentinH]

Summary

• Replaces the class component with a Hooks engine using one mount effect plus an internal SSR-safe layout effect.
• Targets React 19.2 and React Compiler; no manual callback or memo hooks.
• Modernizes refs, stylesheet handling, callback semantics, demo, docs, and migration guidance.
• Adds StrictMode, SSR, interaction lifecycle, media-switch, and built-package CJS/ESM coverage.

Breaking changes

• Requires React 19.2.
• Component ref now targets the outer DOM container; legacy setter refs and the public class instance are removed.
• Automatic CSS uses React-managed stylesheet resources, with an inline nonce path for SSR.
• Callback emissions are deduplicated and tied to committed controlled values.

Verification

• pnpm type-check
• pnpm lint
• pnpm unit (54 tests)
• pnpm build
• pnpm docs:build
• pnpm exec vite build ./examples --config ./vite.config.mts
• pnpm e2e (28 tests)

Release: major.

📦 Published PR as canary version: 7.0.0--canary.664.d002ada.0

✨ Test out this PR locally via:

npm install react-easy-crop@7.0.0--canary.664.d002ada.0
# or 
yarn add react-easy-crop@7.0.0--canary.664.d002ada.0

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​babel__core@​7.20.5
	@​types/​react-dom@​18.0.10 ⏵ 19.2.4	+1			+9
	@​types/​react@​18.0.28 ⏵ 19.2.18	+1		+1	-5
	babel-plugin-react-compiler@​1.0.0
	@​babel/​core@​7.20.12 ⏵ 7.29.7	+1	+1		-6
	react@​18.2.0 ⏵ 19.2.8	+1
	@​testing-library/​dom@​10.4.1
	@​rolldown/​plugin-babel@​0.2.3
	@​testing-library/​react@​16.3.2
	react-dom@​18.2.0 ⏵ 19.2.8			+1
	jsdom@​29.1.1
	@​vitejs/​plugin-react@​6.0.5
	eslint-plugin-react-hooks@​4.6.0 ⏵ 7.1.1			+8

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm data-urls is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/jsdom@29.1.1 → npm/data-urls@7.0.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/data-urls@7.0.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm jsdom is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: package.json → npm/jsdom@29.1.1 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/jsdom@29.1.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[ValentinH]

Standards

No documented standards; no hard violations. All findings are baseline judgement calls:

• Repeated Switches — src/useCropper.tsx:1184-1228: both handlers repeat switch (event.key) with case 'ArrowUp', 'ArrowDown', 'ArrowLeft', and 'ArrowRight'. Define one arrow-delta map/type guard and reuse it.

• Duplicated Code — src/useCropper.tsx:1116-1144: function setImageElement(...) and function setVideoElement(...) repeat runtime.media = element, const refCleanup = assignRef(mediaRef, element), and equivalent cleanup. Extract a typed media-ref callback factory/helper.

• Data Clumps — src/useCropper.tsx:102-103,358-359,1052-1061: cropSizeWidth?: number and cropSizeHeight?: number always travel and compare together, including previous.cropSizeWidth !== requestedCropSize?.width and the matching height check. Store cropSize?: Size in CommittedInputs and compare through sizesEqual; scalar effect dependencies may remain separate.

• Duplicated Code — tsdown.config.mts:29-32, vite.config.mts:8-11, vitest.config.mts:7-11: all repeat presets: [reactCompilerPreset({ target: '19', panicThreshold: 'all_errors' })]. Centralize the compiler options/preset factory so build, demo, and tests cannot drift.

Spec

• Incorrect implementation — “Use all the best practices” / “Rely on the React compiler…”: src/useCropper.tsx:616-903 creates Effect Events subsequently passed to requestAnimationFrame, timers, and document listeners from ordinary interaction paths entered via JSX handlers at src/useCropper.tsx:1155-1171. React permits Effect Events only from Effects or other Effect Events; the React.useEffectEvent namespace spelling currently bypasses the hooks linter's call-site check. Route these async callbacks through effect-owned subscriptions (or a non-Effect-Event latest-handler primitive) and reserve Effect Events for effect-owned calls.

• Partial migration — “Today is the day we finally migrate to Hooks.”: docs/package.json:22 still installs react-easy-crop 5.5.6. The deployed documentation examples import that package, so they continue running the old class implementation while the docs describe v7 behavior; the new docs CI build validates neither the hooks engine nor its stylesheet/callback changes. Make the docs consume the local v7 build/workspace package.

Summary: Standards — 4 judgement-call findings; worst: duplicated Compiler configuration can drift across build, demo, and tests. Spec — 2 findings; worst: interaction-path Effect Events violate React's call-site contract.

[ValentinH]

Closing this PR after reviewing the trade-offs. The migration increases source complexity and bundle size, introduces breaking API changes, and requires React 19.2, without a demonstrated consumer benefit sufficient to justify those costs.

The existing class implementation remains supported by React. For this library, keeping the implementation small and stable takes priority over adopting newer patterns.

There is useful work here, particularly the regression tests and SSR/callback improvements, which we can evaluate separately. We can revisit a hooks migration if it enables a concrete improvement for consumers.