feat(android): ship the app and plugin gradle files with the CLI

The gradle build scripts used to live only in the android runtime, so any fix to them had to wait for a runtime release. This bundles the app-level gradle files in `vendor/gradle-app` and copies them over the ones the runtime lays down when the platform is added, the same way the plugin build already uses `vendor/gradle-plugin`. - `vendor/gradle-app` holds `build.gradle`, `settings.gradle`, `app/build.gradle`, `app/gradle.properties` and the `app/gradle-helpers`. They are copied on top of the runtime files in `createProject`, so the runtime keeps providing everything that is not part of the overlay. - `--no-override-runtime-gradle-files` opts out and keeps the runtime files. - The directory the files come from is resolved through `getGradleFilesPath`, which already understands an `android.gradleFilesPackageName` config key so the files can later be provided by an npm package instead of the bundled copy. - The CLI now interpolates `__PACKAGE__` (android namespace) and `USER_PROJECT_ROOT` in the copied files, and honours `android.gradleVersion` by rewriting the gradle wrapper. - `--gradleArgs` becomes an array option, so it can be passed several times, and a single value may hold several space separated arguments. Arguments listed in `android.gradleArgs` are passed too, before the command line ones. Both app and plugin builds go through the same merge. - Both app and plugin gradle invocations now get `-PcompileSdk`, `-PtargetSdk`, `-PbuildToolsVersion`, `-PgenerateTypings`, `-PprojectRoot` and `-PappBuildPath` (the last two also as `-D` so `settings.gradle` can read them before project properties exist). - A debug build is signed when the `--key-store-*` options are passed, which is needed for system app builds. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
NativeScript · farfromrefug · Aug 18, 2026 · Aug 19, 2026 · Aug 19, 2026 · Aug 23, 2026
commit 7dedb573846cd645221d7bcb40fded067572861c
diff --git a/docs/man_pages/project/testing/build-android.md b/docs/man_pages/project/testing/build-android.md
@@ -35,6 +35,8 @@ General | `$ ns build android [--compileSdk <API Level>] [--key-store-path <File
     *   `--env.hiddenSourceMap` - creates sources maps in the root folder (useful for Crashlytics usage with bundled app in release).
 * `--aab` - Specifies that the build will produce an Android App Bundle(`.aab`) file.
 * `--gradleFlavor` - Builds the given product flavor, when the app declares any. `--gradleFlavor foo` runs the `assembleFooDebug`/`assembleFooRelease` gradle task instead of `assembleDebug`/`assembleRelease`.
+* `--gradleArgs` - Passes additional arguments to gradle. Can be passed multiple times, and a single value may hold several space separated arguments. Use the `=` form so the value is not mistaken for another flag, for example `--gradleArgs="-PsomeProperty=value"`. Arguments listed under `android.gradleArgs` in `nativescript.config` are passed too, before these ones.
+* `--no-override-runtime-gradle-files` - If set, keeps the gradle files coming from the android runtime instead of the ones shipped with the CLI.
 * `--force` - If set, skips the application compatibility checks and forces `npm i` to ensure all dependencies are installed. Otherwise, the command will check the application compatibility with the current CLI version and could fail requiring `ns migrate`.
 * `--path <Directory>` - Specifies the directory that contains the project. If not set, the project is searched for in the current directory and all directories above it.
 

diff --git a/docs/man_pages/project/testing/debug-android.md b/docs/man_pages/project/testing/debug-android.md
@@ -39,6 +39,8 @@ Attach the debug tools to a running app in the native emulator | `$ ns debug and
     *   `--env.hiddenSourceMap` - creates sources maps in the root folder (useful for Crashlytics usage with bundled app in release).
 * `--aab` - Specifies that the command will produce and deploy an Android App Bundle.
 * `--gradleFlavor` - Builds the given product flavor, when the app declares any. `--gradleFlavor foo` runs the `assembleFooDebug`/`assembleFooRelease` gradle task instead of `assembleDebug`/`assembleRelease`.
+* `--gradleArgs` - Passes additional arguments to gradle. Can be passed multiple times, and a single value may hold several space separated arguments. Use the `=` form so the value is not mistaken for another flag, for example `--gradleArgs="-PsomeProperty=value"`. Arguments listed under `android.gradleArgs` in `nativescript.config` are passed too, before these ones.
+* `--no-override-runtime-gradle-files` - If set, keeps the gradle files coming from the android runtime instead of the ones shipped with the CLI.
 * `--force` - If set, skips the application compatibility checks and forces `npm i` to ensure all dependencies are installed. Otherwise, the command will check the application compatibility with the current CLI version and could fail requiring `ns migrate`.
 
 <% if(isHtml) { %>

diff --git a/docs/man_pages/project/testing/run-android.md b/docs/man_pages/project/testing/run-android.md
@@ -44,6 +44,8 @@ Start a default emulator if none are running, or run application on all connecte
     *   `--env.hiddenSourceMap` - creates sources maps in the root folder (useful for Crashlytics usage with bundled app in release).
 * `--aab` - Specifies that the command will produce and deploy an Android App Bundle.
 * `--gradleFlavor` - Builds the given product flavor, when the app declares any. `--gradleFlavor foo` runs the `assembleFooDebug`/`assembleFooRelease` gradle task instead of `assembleDebug`/`assembleRelease`.
+* `--gradleArgs` - Passes additional arguments to gradle. Can be passed multiple times, and a single value may hold several space separated arguments. Use the `=` form so the value is not mistaken for another flag, for example `--gradleArgs="-PsomeProperty=value"`. Arguments listed under `android.gradleArgs` in `nativescript.config` are passed too, before these ones.
+* `--no-override-runtime-gradle-files` - If set, keeps the gradle files coming from the android runtime instead of the ones shipped with the CLI.
 * `--force` - If set, skips the application compatibility checks and forces `npm i` to ensure all dependencies are installed. Otherwise, the command will check the application compatibility with the current CLI version and could fail requiring `ns migrate`.
 
 <% if(isHtml) { %>

diff --git a/lib/data/build-data.ts b/lib/data/build-data.ts
@@ -53,7 +53,7 @@ export class AndroidBuildData extends BuildData {
 	public androidBundle: boolean;
 	public gradleFlavor: string;
 	public gradlePath: string;
-	public gradleArgs: string;
+	public gradleArgs: string[];
 	public hostProjectPath: string;
 
 	constructor(projectDir: string, platform: string, data: any) {

diff --git a/lib/declarations.d.ts b/lib/declarations.d.ts
@@ -578,7 +578,13 @@ interface IAndroidOptions extends IEmbedOptions {
 	 */
 	gradleFlavor: string;
 	gradlePath: string;
-	gradleArgs: string;
+	gradleArgs: string[];
+	/**
+	 * When true (the default) the gradle files bundled with the CLI are copied
+	 * over the ones shipped by the android runtime. Pass `--no-override-runtime-gradle-files`
+	 * to keep the runtime files untouched.
+	 */
+	overrideRuntimeGradleFiles: boolean;
 }
 
 interface IIOSOptions extends IEmbedOptions {}

diff --git a/lib/definitions/android-plugin-migrator.d.ts b/lib/definitions/android-plugin-migrator.d.ts
@@ -11,7 +11,7 @@ interface IAndroidBuildOptions {
 	aarOutputDir: string;
 	tempPluginDirPath: string;
 	gradlePath?: string;
-	gradleArgs?: string;
+	gradleArgs?: string[];
 }
 
 interface IAndroidPluginBuildService {
@@ -48,5 +48,5 @@ interface IBuildAndroidPluginData extends Partial<IProjectDir> {
 	/**
 	 * Optional custom Gradle arguments.
 	 */
-	gradleArgs?: string;
+	gradleArgs?: string[];
 }
diff --git a/lib/definitions/build.d.ts b/lib/definitions/build.d.ts
@@ -33,7 +33,7 @@ interface IAndroidBuildData
 		IHasAndroidBundle {
 	gradleFlavor?: string;
 	gradlePath?: string;
-	gradleArgs?: string;
+	gradleArgs?: string[];
 }
 
 interface IAndroidSigningData {

diff --git a/lib/definitions/gradle.d.ts b/lib/definitions/gradle.d.ts
@@ -30,4 +30,5 @@ interface IGradleBuildService {
 interface IGradleBuildArgsService {
 	getBuildTaskArgs(buildData: IAndroidBuildData): Promise<string[]>;
 	getCleanTaskArgs(buildData: IAndroidBuildData): string[];
+	getBuildLoggingArgs(): string[];
 }
diff --git a/lib/definitions/project.d.ts b/lib/definitions/project.d.ts
@@ -179,6 +179,25 @@ interface INsConfigAndroid extends INsConfigPlaform {
 	 * Custom runtime package name
 	 */
 	runtimePackageName?: string;
+
+	/**
+	 * Pin the gradle wrapper to a specific gradle version, overriding the one
+	 * shipped by the android runtime.
+	 */
+	gradleVersion?: string;
+
+	/**
+	 * Additional arguments passed to every gradle invocation (app and plugin
+	 * builds). Merged with the ones passed on the command line through
+	 * `--gradleArgs`.
+	 */
+	gradleArgs?: string[];
+
+	/**
+	 * Package providing the gradle files copied over the ones shipped by the
+	 * android runtime. Defaults to the files bundled with the CLI.
+	 */
+	gradleFilesPackageName?: string;
 }
 
 interface INsConfigHooks {

diff --git a/lib/options.ts b/lib/options.ts
@@ -221,7 +221,12 @@ export class Options {
 			},
 			gradleFlavor: { type: OptionType.String, hasSensitiveValue: false },
 			gradlePath: { type: OptionType.String, hasSensitiveValue: false },
-			gradleArgs: { type: OptionType.String, hasSensitiveValue: false },
+			gradleArgs: { type: OptionType.Array, hasSensitiveValue: false },
+			overrideRuntimeGradleFiles: {
+				type: OptionType.Boolean,
+				default: true,
+				hasSensitiveValue: false,
+			},
 			hostProjectPath: { type: OptionType.String, hasSensitiveValue: false },
 			hostProjectModuleName: {
 				type: OptionType.String,

diff --git a/lib/services/android-plugin-build-service.ts b/lib/services/android-plugin-build-service.ts
@@ -38,6 +38,8 @@ import { injector } from "../common/yok";
 import * as _ from "lodash";
 import { resolvePackageJSONPath } from "@rigor789/resolve-package-path";
 import { cwd } from "process";
+import { IAndroidToolsInfo } from "../declarations";
+import { IGradleBuildArgsService } from "../definitions/gradle";
 
 export class AndroidPluginBuildService implements IAndroidPluginBuildService {
 	private get $platformsDataService(): IPlatformsDataService {
@@ -46,7 +48,9 @@ export class AndroidPluginBuildService implements IAndroidPluginBuildService {
 
 	constructor(
 		private $fs: IFileSystem,
+		private $androidToolsInfo: IAndroidToolsInfo,
 		private $childProcess: IChildProcess,
+		private $gradleBuildArgsService: IGradleBuildArgsService,
 		private $hostInfo: IHostInfo,
 		private $options: IOptions,
 		private $logger: ILogger,
@@ -263,7 +267,9 @@ export class AndroidPluginBuildService implements IAndroidPluginBuildService {
 			);
 			await this.buildPlugin({
 				gradlePath: options.gradlePath,
-				gradleArgs: options.gradleArgs,
+				gradleArgs: (
+					this.$projectData.nsConfig?.android?.gradleArgs ?? []
+				).concat(options.gradleArgs ?? []),
 				pluginDir: pluginTempDir,
 				pluginName: options.pluginName,
 				projectDir: options.projectDir,
@@ -413,10 +419,11 @@ export class AndroidPluginBuildService implements IAndroidPluginBuildService {
 		this.addCompileDependencies(platformsAndroidDirPath, buildGradlePath);
 		const runtimeGradleVersions =
 			await this.getRuntimeGradleVersions(projectDir);
-		this.replaceGradleVersion(
-			pluginTempDir,
-			runtimeGradleVersions.gradleVersion,
-		);
+		// a gradle version pinned in the project config wins over the runtime one
+		const gradleVersion =
+			this.$projectData.nsConfig?.android?.gradleVersion ??
+			runtimeGradleVersions.gradleVersion;
+		this.replaceGradleVersion(pluginTempDir, gradleVersion);
 		this.replaceGradleAndroidPluginVersion(
 			buildGradlePath,
 			runtimeGradleVersions.gradleAndroidPluginVersion,
@@ -808,22 +815,38 @@ export class AndroidPluginBuildService implements IAndroidPluginBuildService {
 			pluginBuildSettings.gradlePath ??
 			(this.$hostInfo.isWindows ? "gradlew.bat" : "./gradlew");
 
+		const toolsInfo = this.$androidToolsInfo.getToolsInfo({
+			projectDir: this.$projectData.projectDir,
+		});
+
 		const localArgs = [
 			"-p",
 			pluginBuildSettings.pluginDir,
 			"assembleRelease",
 			`-PtempBuild=true`,
+			`-PcompileSdk=${toolsInfo.compileSdkVersion}`,
+			`-PtargetSdk=${toolsInfo.targetSdkVersion}`,
+			`-PbuildToolsVersion=${toolsInfo.buildToolsVersion}`,
+			`-PprojectRoot=${this.$projectData.projectDir}`,
+			// settings.gradle runs before the project properties are available,
+			// so the same values have to be passed as system properties too
+			`-DprojectRoot=${this.$projectData.projectDir}`,
+			`-PappBuildPath=${this.$projectData.getBuildRelativeDirectoryPath()}`,
+			`-DappBuildPath=${this.$projectData.getBuildRelativeDirectoryPath()}`,
 			`-PappPath=${this.$projectData.getAppDirectoryPath()}`,
 			`-PappResourcesPath=${this.$projectData.getAppResourcesDirectoryPath()}`,
 		];
 
-		if (pluginBuildSettings.gradleArgs) {
-			localArgs.push(pluginBuildSettings.gradleArgs);
+		for (const gradleArg of pluginBuildSettings.gradleArgs ?? []) {
+			localArgs.push(
+				...gradleArg
+					.split(" ")
+					.map((arg) => arg.trim())
+					.filter((arg) => !!arg),
+			);
 		}
 
-		if (this.$logger.getLevel() === "INFO") {
-			localArgs.push("--quiet");
-		}
+		localArgs.push(...this.$gradleBuildArgsService.getBuildLoggingArgs());
 
 		const opts: any = {
 			cwd: pluginBuildSettings.pluginDir,

diff --git a/lib/services/android-project-service.ts b/lib/services/android-project-service.ts
@@ -47,6 +47,7 @@ import {
 import { IInjector } from "../common/definitions/yok";
 import { injector } from "../common/yok";
 import { INotConfiguredEnvOptions } from "../common/definitions/commands";
+import { resolvePackageJSONPath } from "@rigor789/resolve-package-path";
 
 interface NativeDependency {
 	name: string;
@@ -363,10 +364,57 @@ export class AndroidProjectService
 			"-R",
 		);
 
+		this.overrideRuntimeGradleFiles(projectData);
+
 		// TODO: Check if we actually need this and if it should be targetSdk or compileSdk
 		this.cleanResValues(targetSdkVersion, projectData);
 	}
 
+	/**
+	 * Copies the gradle files shipped with the CLI over the ones the android
+	 * runtime just laid down, so the build scripts can be fixed without waiting
+	 * for a runtime release. Opt out with `--no-override-runtime-gradle-files`.
+	 */
+	private overrideRuntimeGradleFiles(projectData: IProjectData): void {
+		if (!this.$options.overrideRuntimeGradleFiles) {
+			this.$logger.trace(
+				"Skipping the gradle files bundled with the CLI - the ones from the android runtime are kept."
+			);
+			return;
+		}
+
+		const gradleFilesPath = this.getGradleFilesPath(projectData);
+		this.$logger.trace(`Applying gradle files from '${gradleFilesPath}'.`);
+		this.$fs.copyFile(
+			path.join(gradleFilesPath, "*"),
+			this.getPlatformData(projectData).projectRoot
+		);
+	}
+
+	/**
+	 * Resolves the directory holding the gradle files copied over the runtime
+	 * ones. Defaults to the copy bundled with the CLI, but a project may point
+	 * `android.gradleFilesPackageName` at an npm package shipping its own.
+	 */
+	private getGradleFilesPath(projectData: IProjectData): string {
+		const packageName = projectData.nsConfig?.android?.gradleFilesPackageName;
+		if (!packageName) {
+			return path.resolve(path.join(__dirname, "../../vendor/gradle-app"));
+		}
+
+		const packageJsonPath = resolvePackageJSONPath(packageName, {
+			paths: [projectData.projectDir],
+		});
+
+		if (!packageJsonPath) {
+			this.$errors.fail(
+				`Unable to resolve '${packageName}', configured as 'android.gradleFilesPackageName'. Make sure it is installed in the project.`
+			);
+		}
+
+		return path.dirname(packageJsonPath);
+	}
+
 	private getResDestinationDir(projectData: IProjectData): string {
 		const appResourcesDirStructureHasMigrated =
 			this.$androidResourcesMigrationService.hasMigrated(
@@ -468,6 +516,28 @@ export class AndroidProjectService
 			this.getProjectNameFromId(projectData),
 			gradleSettingsFilePath,
 		);
+		this.sedFile(
+			gradleSettingsFilePath,
+			/def USER_PROJECT_ROOT = "\$rootDir\/\.\.\/\.\.\/"/,
+			`def USER_PROJECT_ROOT = "$rootDir/${this.getProjectRootRelativePath(
+				projectData
+			)}"`
+		);
+
+		const gradleVersion = projectData.nsConfig?.android?.gradleVersion;
+		if (gradleVersion) {
+			// the project pinned a gradle version - point the wrapper at it
+			this.sedFile(
+				path.join(
+					this.getPlatformData(projectData).projectRoot,
+					"gradle",
+					"wrapper",
+					"gradle-wrapper.properties"
+				),
+				/gradle-([0-9.]+)-bin.zip/,
+				`gradle-${gradleVersion}-bin.zip`
+			);
+		}
 
 		try {
 			// will replace applicationId in app/App_Resources/Android/app.gradle if it has not been edited by the user
@@ -497,6 +567,47 @@ export class AndroidProjectService
 			projectData.projectIdentifiers.android,
 			manifestPath,
 		);
+
+		const projectRoot = this.getPlatformData(projectData).projectRoot;
+		// the gradle files bundled with the CLI declare the android namespace and
+		// resolve the project root themselves - both are placeholders until now
+		this.sedFile(
+			path.join(projectRoot, "app", "build.gradle"),
+			/__PACKAGE__/,
+			projectData.projectIdentifiers.android
+		);
+		this.sedFile(
+			path.join(projectRoot, "build.gradle"),
+			/project\.ext\.USER_PROJECT_ROOT = "\$rootDir\/\.\.\/\.\."/,
+			`project.ext.USER_PROJECT_ROOT = "$rootDir/${this.getProjectRootRelativePath(
+				projectData
+			)}"`
+		);
+	}
+
+	private sedFile(
+		filePath: string,
+		pattern: RegExp,
+		replacement: string
+	): void {
+		if (!this.$fs.exists(filePath)) {
+			return;
+		}
+
+		shell.sed("-i", pattern, replacement, filePath);
+	}
+
+	/**
+	 * Path from the generated android project back to the project root. Not
+	 * always `../..` - the platforms directory can live outside the project.
+	 */
+	private getProjectRootRelativePath(projectData: IProjectData): string {
+		return path
+			.relative(
+				this.getPlatformData(projectData).projectRoot,
+				projectData.projectDir
+			)
+			.replace(/\\/g, "/");
 	}
 
 	private getProjectNameFromId(projectData: IProjectData): string {