feat(Worklets): expose plugin options type (#8632)

tjzel · web-flow · commit 7bd206b46f94 · 2025-11-21T11:40:22.000Z
## Summary Now the users can have typed configs with TSDoc and more. Our users can now do ```js /** @type {import('react-native-worklets/plugin').PluginOptions} */ const workletOptions = { // auto-suggestions here 🚀 }; ``` ## Test plan CI
diff --git a/.gitattributes b/.gitattributes
@@ -3,3 +3,5 @@
 /.yarn/plugins/**/* binary=true
 /packages/eslint-plugin-reanimated/index.js linguist-generated=true
 /packages/eslint-plugin-reanimated/types/**/* linguist-generated=true
+/packages/react-native-worklets/plugin/index.js linguist-generated=true
+/packages/react-native-worklets/plugin/index.d.ts linguist-generated=true
diff --git a/apps/fabric-example/babel.config.js b/apps/fabric-example/babel.config.js
@@ -1,14 +1,14 @@
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {
+  // Uncomment the next line to enable bundle mode.
+  // bundleMode: true,
+};
+
 /** @type {import('@babel/core').TransformOptions} */
 module.exports = {
   presets: ['module:@react-native/babel-preset'],
   plugins: [
-    [
-      'react-native-worklets/plugin',
-      {
-        // Uncomment the next line to enable bundle mode.
-        // bundleMode: true,
-      },
-    ],
+    ['react-native-worklets/plugin', workletsPluginOptions],
     [
       'module-resolver',
       {
diff --git a/apps/macos-example/babel.config.js b/apps/macos-example/babel.config.js
@@ -1,3 +1,6 @@
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {};
+
 /** @type {import('@babel/core').TransformOptions} */
 module.exports = {
   presets: ['module:@react-native/babel-preset'],
@@ -12,6 +15,6 @@ module.exports = {
         extensions: ['.js', '.jsx', '.ts', '.tsx'],
       },
     ],
-    'react-native-worklets/plugin',
+    ['react-native-worklets/plugin', workletsPluginOptions],
   ],
 };
diff --git a/apps/next-example/babel.config.js b/apps/next-example/babel.config.js
@@ -1,3 +1,6 @@
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {};
+
 /** @type {import('@babel/core').TransformOptions} */
 module.exports = {
   presets: ['next/babel'],
@@ -13,6 +16,6 @@ module.exports = {
         },
       },
     ],
-    'react-native-worklets/plugin',
+    ['react-native-worklets/plugin', workletsPluginOptions],
   ],
 };
diff --git a/apps/tvos-example/babel.config.js b/apps/tvos-example/babel.config.js
@@ -1,5 +1,8 @@
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {};
+
 /** @type {import('@babel/core').TransformOptions} */
 module.exports = {
   presets: ['module:@react-native/babel-preset'],
-  plugins: ['react-native-worklets/plugin'],
+  plugins: [['react-native-worklets/plugin', workletsPluginOptions]],
 };
diff --git a/apps/web-example/babel.config.js b/apps/web-example/babel.config.js
@@ -1,3 +1,6 @@
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {};
+
 /** @type {import('@babel/core').ConfigFunction} */
 module.exports = function (api) {
   const plugins = [
@@ -18,7 +21,7 @@ module.exports = function (api) {
   if (disableBabelPlugin) {
     console.log('Starting Web example without Babel plugin.');
   } else {
-    plugins.push('react-native-worklets/plugin');
+    plugins.push(['react-native-worklets/plugin', workletsPluginOptions]);
   }
 
   return {
diff --git a/packages/react-native-reanimated/babel.config.js b/packages/react-native-reanimated/babel.config.js
@@ -1,3 +1,6 @@
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = { disableInlineStylesWarning: true };
+
 /** @type {import('@babel/core').TransformOptions} */
 module.exports = {
   presets: [
@@ -12,7 +15,5 @@ module.exports = {
     '@babel/preset-typescript',
     'module:@react-native/babel-preset',
   ],
-  plugins: [
-    ['react-native-worklets/plugin', { disableInlineStylesWarning: true }],
-  ],
+  plugins: [['react-native-worklets/plugin', workletsPluginOptions]],
 };
diff --git a/packages/react-native-reanimated/package.json b/packages/react-native-reanimated/package.json
@@ -62,6 +62,7 @@
     "compatibility.json",
     "mock.js",
     "plugin/index.js",
+    "plugin/index.d.ts",
     "metro-config",
     "!**/__tests__",
     "!**/__fixtures__",
diff --git a/packages/react-native-reanimated/plugin/index.d.ts b/packages/react-native-reanimated/plugin/index.d.ts
@@ -0,0 +1 @@
+export type { PluginOptions } from 'react-native-worklets/plugin/';
diff --git a/packages/react-native-worklets/package.json b/packages/react-native-worklets/package.json
@@ -104,6 +104,7 @@
     "scripts/worklets_utils.rb",
     "scripts/validate-react-native-version.js",
     "plugin/index.js",
+    "plugin/index.d.ts",
     "*.podspec",
     "react-native.config.js",
     "!apple/build",
diff --git a/packages/react-native-worklets/plugin/.gitignore b/packages/react-native-worklets/plugin/.gitignore
@@ -1,2 +1,3 @@
-lib
+lib/
+types/
 index.js.map
diff --git a/packages/react-native-worklets/plugin/.prettierignore b/packages/react-native-worklets/plugin/.prettierignore
@@ -1,3 +1,5 @@
 index.js
 index.js.map
+index.d.ts
 lib/
+types/
diff --git a/packages/react-native-worklets/plugin/babel.config.js b/packages/react-native-worklets/plugin/babel.config.js
@@ -1,15 +1,13 @@
 // This file is needed for manual tests of the plugin.
 const workletsPlugin = require('./index.js');
 
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {
+  // bundleMode: true,
+};
+
 /** @type {import('@babel/core').TransformOptions} */
 module.exports = {
   presets: ['@babel/preset-typescript'],
-  plugins: [
-    [
-      workletsPlugin,
-      {
-        // bundleMode: true,
-      },
-    ],
-  ],
+  plugins: [[workletsPlugin, workletsPluginOptions]],
 };
diff --git a/packages/react-native-worklets/plugin/index.d.ts b/packages/react-native-worklets/plugin/index.d.ts
diff --git a/packages/react-native-worklets/plugin/package.json b/packages/react-native-worklets/plugin/package.json
@@ -22,9 +22,9 @@
   "license": "MIT",
   "readmeFilename": "README.md",
   "scripts": {
-    "build": "yarn tsc && yarn bundle && yarn format",
+    "build": "yarn tsc && yarn bundle && yarn format && cp types/options.d.ts index.d.ts",
     "bundle": "node bundle.js",
-    "format": "prettier --write --list-different src",
+    "format": "prettier --write --ignore-path '' --log-level silent types/options.d.ts && prettier --write --list-different src",
     "watch": "tsc-watch --onSuccess \"yarn bundle\"",
     "lint": "eslint --max-warnings=0 src",
     "type:check": "tsc --noEmit"
diff --git a/packages/react-native-worklets/plugin/src/options.ts b/packages/react-native-worklets/plugin/src/options.ts
@@ -0,0 +1,110 @@
+export interface PluginOptions {
+  /**
+   * Enables the [Bundle
+   * Mode](https://docs.swmansion.com/react-native-worklets/docs/experimental/bundle-mode).
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#bundle-mode}
+   *
+   * - Defaults to `false`.
+   */
+  bundleMode?: boolean;
+
+  /**
+   * Turning on this option suppresses a helpful warning when you use [inline
+   * shared
+   * values](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animations-in-inline-styling).
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#disableinlinestyleswarning}
+   *
+   * - Defaults to `false`.
+   */
+  disableInlineStylesWarning?: boolean;
+
+  /**
+   * This option turns off the source map generation for worklets. Mostly used
+   * for testing purposes.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#disablesourcemaps}
+   *
+   * - Defaults to `false`.
+   */
+  disableSourceMaps?: boolean;
+
+  /**
+   * This is a list of Babel plugins that will be used when transforming
+   * worklets' code with Worklets Babel Plugin.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#extraplugins}
+   *
+   * - Defaults to an empty array `[]`.
+   */
+  extraPlugins?: string[];
+
+  /**
+   * This is a list of Babel presets that will be used when transforming
+   * worklets' code with Worklets Babel Plugin.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#extrapresets}
+   *
+   * - Defaults to an empty array `[]`.
+   */
+  extraPresets?: string[];
+
+  /**
+   * This is a list of identifiers (objects) that will not be copied to the UI
+   * thread if a worklet requires them.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#globals}
+   *
+   * - Defaults to an empty array `[]`.
+   */
+  globals?: string[];
+
+  /**
+   * This option comes in handy for Web apps. Because Babel ordinarily doesn't
+   * get information about the target platform, it includes worklet data in the
+   * bundle that only Native apps find relevant. If you enable this option, your
+   * bundle size will be smaller.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#omitnativeonlydata}
+   *
+   * - Defaults to `false`.
+   */
+  omitNativeOnlyData?: boolean;
+
+  /**
+   * This option dictates the passed file location for a worklet's source map.
+   * If you enable this option, the file paths will be relative to `process.cwd`
+   * (the current directory where Babel executes). This can be handy for Jest
+   * test snapshots to ensure consistent results across machines.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#relativesourcelocation}
+   *
+   * - Defaults to `false`.
+   */
+  relativeSourceLocation?: boolean;
+
+  /**
+   * This option can also be useful for Web apps. In Reanimated, there are
+   * numerous checks to determine the right function implementation for a
+   * specific target platform. Enabling this option changes all the checks that
+   * identify if the target is a Web app to `true`. This alteration can aid in
+   * tree-shaking and contribute to reducing the bundle size.
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#substitutewebplatformchecks}
+   *
+   * - Defaults to `false`.
+   */
+  substituteWebPlatformChecks?: boolean;
+
+  /**
+   * This option allows you to register modules as safe to use on Worklet
+   * Runtimes in the [Bundle
+   * Mode](https://docs.swmansion.com/react-native-worklets/docs/experimental/bundle-mode).
+   *
+   * {@link https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/plugin-options#workletizablemodules}
+   *
+   * - Defaults to an empty array `[]`.
+   */
+  workletizableModules?: string[];
+}
diff --git a/packages/react-native-worklets/plugin/src/types.ts b/packages/react-native-worklets/plugin/src/types.ts
@@ -15,23 +15,12 @@ import {
   isObjectMethod,
 } from '@babel/types';
 
-export interface WorkletsPluginOptions {
-  relativeSourceLocation?: boolean;
-  disableInlineStylesWarning?: boolean;
-  omitNativeOnlyData?: boolean;
-  globals?: string[];
-  substituteWebPlatformChecks?: boolean;
-  disableSourceMaps?: boolean;
-  extraPlugins?: string[];
-  extraPresets?: string[];
-  bundleMode?: boolean;
-  workletizableModules?: string[];
-}
+import type { PluginOptions } from './options';
 
 export interface WorkletsPluginPass {
   file: BabelFile;
   key: string;
-  opts: WorkletsPluginOptions;
+  opts: PluginOptions;
   cwd: string;
   filename: string | undefined;
   workletNumber: number;
diff --git a/packages/react-native-worklets/plugin/tsconfig.json b/packages/react-native-worklets/plugin/tsconfig.json
@@ -10,7 +10,8 @@
     "esModuleInterop": true,
     "outDir": "lib",
     "rootDir": "src",
-    "declaration": false,
+    "declarationDir": "types",
+    "declaration": true,
     "noEmit": false
   },
   "include": ["src"]
diff --git a/scripts/patches/bundle-mode.patch b/scripts/patches/bundle-mode.patch
@@ -36,18 +36,18 @@ index afaf8c45a5..c3c5434878 100644
 +    }
 +}
 diff --git a/apps/fabric-example/babel.config.js b/apps/fabric-example/babel.config.js
-index 259ed1ad84..ebdbea9d22 100644
+index 3c9372b6ae..8043395b1c 100644
 --- a/apps/fabric-example/babel.config.js
 +++ b/apps/fabric-example/babel.config.js
-@@ -6,7 +6,7 @@ module.exports = {
-       'react-native-worklets/plugin',
-       {
-         // Uncomment the next line to enable bundle mode.
--        // bundleMode: true,
-+        bundleMode: true,
-       },
-     ],
-     [
+@@ -1,7 +1,7 @@
+ /** @type {import('react-native-worklets/plugin').PluginOptions} */
+ const workletsPluginOptions = {
+   // Uncomment the next line to enable bundle mode.
+-  // bundleMode: true,
++  bundleMode: true,
+ };
+ 
+ /** @type {import('@babel/core').TransformOptions} */
 diff --git a/apps/fabric-example/ios/Podfile b/apps/fabric-example/ios/Podfile
 index 3f8fe4a6e2..e208389ca3 100644
 --- a/apps/fabric-example/ios/Podfile
@@ -62,10 +62,10 @@ index 3f8fe4a6e2..e208389ca3 100644
  platform :ios, min_ios_version_supported
  prepare_react_native_project!
 diff --git a/apps/fabric-example/metro.config.js b/apps/fabric-example/metro.config.js
-index ac70ff22bc..cb06730da7 100644
+index 67158b31ff..3990fe93c2 100644
 --- a/apps/fabric-example/metro.config.js
 +++ b/apps/fabric-example/metro.config.js
-@@ -33,8 +33,8 @@ let config = {
+@@ -20,8 +20,8 @@ let config = {
  config = mergeConfig(getDefaultConfig(__dirname), config);
  
  // Uncomment the following to enable bundle mode.
@@ -77,10 +77,10 @@ index ac70ff22bc..cb06730da7 100644
  module.exports = wrapWithReanimatedMetroConfig(
    mergeConfig(getDefaultConfig(__dirname), config)
 diff --git a/package.json b/package.json
-index f020af7a46..9f9727afb9 100644
+index 141335c036..1261072923 100644
 --- a/package.json
 +++ b/package.json
-@@ -69,5 +69,10 @@
+@@ -70,5 +70,10 @@
      "react-native-builder-bob": "0.40.13",
      "shelljs": "0.10.0",
      "typescript": "5.8.3"

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export type { PluginOptions } from 'react-native-worklets/plugin/';`