feat: expose Brownfield Gradle Plugin as node module

.changeset/brownfield-gradle-plugin-source.md

@@ -0,0 +1,5 @@
+---
+'@callstack/react-native-brownfield': patch
+---
+
+Expose the Brownfield Android Gradle Plugin source from the npm package for opt-in local patching.

docs/docs/docs/getting-started/android.mdx

@@ -59,6 +59,57 @@ react {
 }
 ```
 
+### Advanced: Load the Plugin from Node Modules
+
+Use the source version only when you need to patch the Brownfield Gradle Plugin locally, for example with `patch-package`.
+
+Add the included build to the top of `android/settings.gradle.kts`:
+
+```kotlin
+pluginManagement {
+    includeBuild(
+        File(
+            providers.exec {
+                workingDir(rootDir)
+                commandLine("node", "--print", "require.resolve('@callstack/react-native-brownfield/package.json')")
+            }.standardOutput.asText.get().trim()
+        ).parentFile.resolve("gradle-plugin/brownfield")
+    )
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+```
+
+For standard React Native app layouts, this shorter form also works:
+
+```kotlin
+pluginManagement {
+    includeBuild("../node_modules/@callstack/react-native-brownfield/gradle-plugin/brownfield")
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+```
+
+Then remove the Maven classpath dependency from `android/build.gradle`:
+
+```diff
+- classpath("com.callstack.react:brownfield-gradle-plugin:<version>")
+```
+
+Keep applying the plugin in your brownfield Android library module as usual:
+
+```kotlin
+plugins {
+    id("com.callstack.react.brownfield")
+}
+```
+
 ## 3. Add React Native Dependencies
 
 Add the code below to `reactnativeapp/build.gradle.kts` based on your React Native version.

gradle-plugins/react/README.md

@@ -83,6 +83,42 @@ react {
  val appProject = project(":app")
 ```
 
+### From `node_modules` Source
+
+The Maven dependency is the recommended default because it uses the prebuilt plugin and is faster.
+Use this source-based setup only when you need to patch the Brownfield Gradle Plugin locally. See the [Android integration docs](../../docs/docs/docs/getting-started/android.mdx#advanced-load-the-plugin-from-node-modules) for details.
+
+Add this to the top of `android/settings.gradle.kts`:
+
+```kotlin
+pluginManagement {
+    includeBuild(
+        File(
+            providers.exec {
+                workingDir(rootDir)
+                commandLine("node", "--print", "require.resolve('@callstack/react-native-brownfield/package.json')")
+            }.standardOutput.asText.get().trim()
+        ).parentFile.resolve("gradle-plugin/brownfield")
+    )
+}
+```
+
+For standard React Native app layouts, this shorter form also works:
+
+```kotlin
+pluginManagement {
+    includeBuild("../node_modules/@callstack/react-native-brownfield/gradle-plugin/brownfield")
+}
+```
+
+Then remove the Maven classpath dependency:
+
+```diff
+- classpath("com.callstack.react:brownfield-gradle-plugin:1.1.0")
+```
+
+Keep using `id("com.callstack.react.brownfield")` in your brownfield Android library module.
+
 ## API Usage
 
 - **About Dependencies**

gradle-plugins/react/brownfield/gradle/libs.versions.toml

@@ -1,5 +1,5 @@
 [versions]
-kotlinJvm = "2.0.21"
+kotlinJvm = "2.2.21"
 ktlint = "12.1.1"
 detekt = "1.23.7"
 agp = "8.5.2"

gradle-plugins/react/brownfield/settings.gradle

@@ -0,0 +1,7 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}

gradle-plugins/react/brownfield/src/main/kotlin/com/callstack/react/brownfield/plugin/ProjectConfigurations.kt

@@ -91,7 +91,7 @@ class ProjectConfigurations(private val project: Project) {
         Logging.log("created configuration $configName ✅")
     }
 
-    private fun <T> copyAttribute(
+    private fun <T : Any> copyAttribute(
         key: Attribute<T>,
         from: AttributeContainer,
         into: AttributeContainer,

packages/react-native-brownfield/.gitignore

@@ -0,0 +1 @@
+/gradle-plugin/

packages/react-native-brownfield/package.json

@@ -49,8 +49,9 @@
     "build": "bob build",
     "dev": "nodemon --exitcrash false --ext '*' --watch src --exec \"bob build\"",
     "build:brownfield": "yarn run build",
-    "prepack": "cp ../../README.md ./README.md",
-    "postpack": "rm ./README.md",
+    "sync:gradle-plugin": "node ./scripts/sync-gradle-plugin-source.js",
+    "prepack": "node ./scripts/sync-gradle-plugin-source.js && cp ../../README.md ./README.md",
+    "postpack": "node ./scripts/sync-gradle-plugin-source.js --clean && rm ./README.md",
     "test": "vitest run"
   },
   "keywords": [
@@ -63,6 +64,7 @@
     "src",
     "lib",
     "scripts",
+    "gradle-plugin",
     "android",
     "ios",
     "cpp",

packages/react-native-brownfield/scripts/sync-gradle-plugin-source.js

@@ -0,0 +1,52 @@
+/**
+ * Copies the Brownfield Gradle plugin source from gradle-plugins/react/brownfield/
+ * into packages/react-native-brownfield/gradle-plugin/brownfield/ so that the
+ * plugin source is included in the published npm package.
+ *
+ * This enables consumers to use the plugin as a composite build via includeBuild
+ * from node_modules instead of downloading it from Maven Central — useful for
+ * local patching or working with an unreleased version.
+ *
+ * Run with --clean to remove the copied output (e.g. after publishing or testing).
+ *
+ * Usage:
+ *   node sync-gradle-plugin-source.js          # copy
+ *   node sync-gradle-plugin-source.js --clean  # remove
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+
+const sourceBrownfieldPath = path.join(
+  repoRoot,
+  'gradle-plugins',
+  'react',
+  'brownfield'
+);
+
+const targetRoot = path.join(packageRoot, 'gradle-plugin');
+const targetBrownfieldPath = path.join(targetRoot, 'brownfield');
+
+if (process.argv.includes('--clean')) {
+  // Remove the copied gradle-plugin directory from the package
+  fs.rmSync(targetRoot, { recursive: true, force: true });
+  process.exit(0);
+}
+
+// Always start from a clean slate to avoid stale files
+fs.rmSync(targetRoot, { recursive: true, force: true });
+
+fs.cpSync(sourceBrownfieldPath, targetBrownfieldPath, {
+  recursive: true,
+  // Exclude Gradle build artefacts and local state that should not be shipped
+  filter(source) {
+    const relativePath = path.relative(sourceBrownfieldPath, source);
+    const parts = relativePath.split(path.sep);
+
+    return !parts.some((part) =>
+      ['build', '.gradle', 'local.properties', '.kotlin', 'bin'].includes(part)
+    );
+  },
+});