Merge pull request #497 from jeremybarbet/feat/babel-plugin-types

feat: add types definitions for the babel plugin + extra docs

docs/src/content/docs/v3/other/babel-plugin.mdx

@@ -180,9 +180,75 @@ import { Image } from 'react-native-unistyles/components/native/Image'
 <Image source={require('./image.png')} style={styles.image} ref={ref2} />
 ```
 
-
 ### Summary
 
 That's it! We hope you enjoy the DX of Unistyles 3.0 with the help of the Babel plugin. If you encounter any Babel issues, we're ready to tackle them and resolve them with priority!
 
+## Additional configuration
+
+The Babel plugin comes with a few additional options to extend its usage.
+
+### `autoProcessImports`
+
+If you use ui-kit components, you can configure the Babel plugin to process them.
+
+```js title="babel.config.js"
+/** @type {import('react-native-unistyles/plugin').UnistylesPluginOptions} */
+const unistylesPluginConfig = {
+    autoProcessImports: ['@lib/ui-kit'],
+}
+
+module.exports = function (api) {
+    api.cache(true)
+
+    return {
+        plugins: [
+            ['react-native-unistyles/plugin', unistylesPluginConfig]
+        ]
+    }
+}
+```
+
+### `autoProcessPaths`
+
+Similar to `autoProcessImports`, you can configure the Babel plugin to process paths.
+
+```js title="babel.config.js"
+/** @type {import('react-native-unistyles/plugin').UnistylesPluginOptions} */
+const unistylesPluginConfig = {
+    autoProcessPaths: ['external-library/components'],
+}
+
+module.exports = function (api) {
+    api.cache(true)
+
+    return {
+        plugins: [
+            ['react-native-unistyles/plugin', unistylesPluginConfig]
+        ]
+    }
+}
+```
+
+### `debug`
+
+In order to debug issues with the Babel plugin you can enable the `debug` boolean.
+
+```js title="babel.config.js"
+/** @type {import('react-native-unistyles/plugin').UnistylesPluginOptions} */
+const unistylesPluginConfig = {
+    debug: true,
+}
+
+module.exports = function (api) {
+    api.cache(true)
+
+    return {
+        plugins: [
+            ['react-native-unistyles/plugin', unistylesPluginConfig]
+        ]
+    }
+}
+```
+
 </Seo>

example/babel.config.js

@@ -1,17 +1,23 @@
 const path = require('path')
 const pak = require('../package.json')
 
+/** @type {import('../plugin').UnistylesPluginOptions} */
+const unistylesPluginConfig = {
+    debug: true,
+    isLocal: true,
+    autoProcessImports: ['@lib/theme', './st'],
+}
+
 module.exports = api => {
     api.cache(true)
 
     return {
         presets: ['module:@react-native/babel-preset'],
         plugins: [
-            [path.join(__dirname, '../plugin'), {
-                debug: true,
-                isLocal: true,
-                autoProcessImports: ['@lib/theme', './st'],
-            }],
+            [
+                path.join(__dirname, '../plugin'),
+                unistylesPluginConfig
+            ],
             [
                 'module-resolver',
                 {

plugin/import.js

@@ -1,3 +1,4 @@
+/** @param {import('./index').UnistylesPluginPass} state */
 function addUnistylesImport(t, path, state) {
     const localNames = Object.keys(state.reactNativeImports)
     const names = Object.values(state.reactNativeImports)

plugin/index.d.ts

@@ -0,0 +1,28 @@
+export interface UnistylesPluginOptions {
+  /**
+   * Logs found dependencies in every StyleSheet
+   */
+  debug?: boolean;
+
+  /**
+   * Only applicable for Unistyles monorepo for
+   * path resolution, don't use it!
+   */
+  isLocal?: boolean;
+
+  /**
+   * A list of imports that should trigger Unistyles
+   * babel plugin eg. `@codemask/ui`
+   */
+  autoProcessImports?: string[]
+
+  /**
+   * A list of paths that should trigger Unistyles babel
+   * plugin, check the default list defined in `REPLACE_WITH_UNISTYLES_PATHS`
+   */
+  autoProcessPaths?: string[];
+}
+
+export interface UnistylesPluginPass {
+  opts: UnistylesPluginOptions;
+}

plugin/index.js

@@ -32,17 +32,12 @@ const REPLACE_WITH_UNISTYLES_PATHS = [
     'react-native-gesture-handler/src/components'
 ]
 
-// options
-// { debug: boolean, isLocal: boolean, autoProcessImports: Array<string>, autoProcessPaths: Array<string> }
-// debug - logs found dependencies in every StyleSheet
-// isLocal - only applicable for Unistyles monorepo for path resolution, don't use it!
-// autoProcessImports - list of imports that should trigger unistyles babel plugin eg. @codemask/ui
-// autoProcessPaths - list of paths that should trigger unistyles babel plugin, check default list above
 module.exports = function ({ types: t }) {
     return {
         name: 'babel-react-native-unistyles',
         visitor: {
             Program: {
+                /** @param {import('./index').UnistylesPluginPass} state */
                 enter(path, state) {
                     state.file.replaceWithUnistyles = REPLACE_WITH_UNISTYLES_PATHS
                         .concat(state.opts.autoProcessPaths ?? [])
@@ -108,6 +103,7 @@ module.exports = function ({ types: t }) {
                     }
                 })
             },
+            /** @param {import('./index').UnistylesPluginPass} state */
             ImportDeclaration(path, state) {
                 if (isInsideNodeModules(state) && !state.file.replaceWithUnistyles) {
                     return

plugin/stylesheet.js

@@ -63,6 +63,7 @@ function addStyleSheetTag(t, path, state) {
     callee.container.arguments.push(t.numericLiteral(uniqueId))
 }
 
+/** @param {import('./index').UnistylesPluginPass} state */
 function analyzeDependencies(t, state, name, unistyleObj, themeName, rtName) {
     const debugMessage = deps => {
         if (state.opts.debug) {