### Install expo-ruler

Source: https://github.com/shubh73/expo-ruler/blob/main/README.md

Install the expo-ruler package using npm or yarn.

```bash
npx expo install expo-ruler
```

--------------------------------

### Customized app.json setup for expo-ruler

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Customize expo-ruler settings in `app.json` for specific device configurations like low-density armeabi-v7a and API 30.

```json
{
  "expo": {
    "plugins": [
      [
        "expo-ruler",
        {
          "abi": "armeabi-v7a",
          "locale": "fr",
          "screenDensity": 240,
          "sdkVersion": 30,
          "rulerVersion": "2.0.0-beta-3"
        }
      ]
    ]
  }
}
```

--------------------------------

### Running Ruler Analysis

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Instructions on how to run the Ruler analysis task using Gradle after executing `npx expo prebuild`.

```APIDOC
## Running Ruler Analysis

After running `npx expo prebuild`, use Gradle to execute the Ruler analysis task:

```bash
# Analyze the release bundle (default variant)
cd android && ./gradlew app:analyzeReleaseBundle

# List all available Ruler tasks (useful for custom build variants)
cd android && ./gradlew tasks --group="Ruler"

# Example output of tasks listing:
# Ruler tasks
# -----------
# analyzeDebugBundle - Analyze the debug bundle with Ruler
# analyzeReleaseBundle - Analyze the release bundle with Ruler

# Reports are written to:
# android/app/build/reports/ruler/release/report.html
# android/app/build/reports/ruler/release/report.json
```
```

--------------------------------

### Run Ruler Analysis with Gradle

Source: https://context7.com/shubh73/expo-ruler/llms.txt

After running `npx expo prebuild`, use Gradle to execute the Ruler analysis task. Reports are written to `android/app/build/reports/ruler/release/report.html` and `android/app/build/reports/ruler/release/report.json`.

```bash
# Analyze the release bundle (default variant)
cd android && ./gradlew app:analyzeReleaseBundle

# List all available Ruler tasks (useful for custom build variants)
cd android && ./gradlew tasks --group="Ruler"

# Example output of tasks listing:
# Ruler tasks
# -----------
# analyzeDebugBundle - Analyze the debug bundle with Ruler
# analyzeReleaseBundle - Analyze the release bundle with Ruler

# Reports are written to:
# android/app/build/reports/ruler/release/report.html
# android/app/build/reports/ruler/release/report.json
```

--------------------------------

### List Available Ruler Tasks

Source: https://github.com/shubh73/expo-ruler/blob/main/README.md

If custom build variants are defined, list all available Ruler tasks.

```bash
cd android && ./gradlew tasks --group="Ruler"
```

--------------------------------

### Analyze Release Bundle with Ruler

Source: https://github.com/shubh73/expo-ruler/blob/main/README.md

Run the analyzeReleaseBundle task from the android directory to generate reports.

```bash
cd android && ./gradlew app:analyzeReleaseBundle
```

--------------------------------

### Handle unknown plugin options with withRuler

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Demonstrates how `withRuler` throws validation errors for unknown plugin options during prebuild.

```typescript
// Unknown key → throws immediately during prebuild
withRuler(config, { unknownOption: true } as any);
// Error: expo-ruler: unknown plugin option "unknownOption". Allowed options: abi, locale, screenDensity, sdkVersion, rulerVersion.
```

--------------------------------

### Apply Ruler Plugin to build.gradle

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Inserts `apply plugin: 'com.spotify.ruler'` after `apply plugin: "com.facebook.react"` in `android/app/build.gradle`. This ensures React Native is initialized before Ruler hooks into the build. The function is idempotent.

```typescript
import { addRulerApplyPlugin } from "expo-ruler/build/withRuler";

const appGradle = `
apply plugin: "com.android.application"
apply plugin: "org.jetbrains.kotlin.android"
apply plugin: "com.facebook.react"

android {
    compileSdkVersion 34
}
`;

const patched = addRulerApplyPlugin(appGradle);
console.log(patched);
/*
apply plugin: "com.android.application"
apply plugin: "org.jetbrains.kotlin.android"
apply plugin: "com.facebook.react"
// @generated begin expo-ruler-apply-plugin - expo prebuild (DO NOT MODIFY)
apply plugin: 'com.spotify.ruler'
// @generated end expo-ruler-apply-plugin

android {
    compileSdkVersion 34
}
*/

// Idempotency guaranteed
const twice = addRulerApplyPlugin(patched);
console.log(twice === patched); // true
```

--------------------------------

### Add Ruler Gradle classpath to build.gradle

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Injects the Spotify Ruler Gradle plugin classpath into the root `android/build.gradle` file. The operation is idempotent and handles version upgrades.

```typescript
import { addRulerClasspath } from "expo-ruler/build/withRuler";

const projectGradle = `
buildscript {
  repositories {
    google()
    mavenCentral()
  }
  dependencies {
    classpath('com.android.tools.build:gradle')
    classpath('com.facebook.react:react-native-gradle-plugin')
  }
}`;

const patched = addRulerClasspath(projectGradle, "2.0.0-beta-3");
console.log(patched);
/*
buildscript {
  repositories {
    google()
    mavenCentral()
  }
  dependencies {
    classpath('com.android.tools.build:gradle')
    // @generated begin expo-ruler-classpath - expo prebuild (DO NOT MODIFY)
    classpath('com.spotify.ruler:ruler-gradle-plugin:2.0.0-beta-3')
    // @generated end expo-ruler-classpath
    classpath('com.facebook.react:react-native-gradle-plugin')
  }
}
*/

// Idempotency — running twice returns the same string
const twice = addRulerClasspath(patched, "2.0.0-beta-3");
console.log(twice === patched); // true

// Version upgrade — old classpath is replaced automatically
const upgraded = addRulerClasspath(patched, "2.0.0-beta-4");
console.log(upgraded.includes("2.0.0-beta-3")); // false
console.log(upgraded.includes("2.0.0-beta-4")); // true
```

--------------------------------

### addRulerApplyPlugin(src)

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Inserts `apply plugin: 'com.spotify.ruler'` into the app-level `build.gradle` file. This function ensures the plugin is applied after React Native initialization.

```APIDOC
## `addRulerApplyPlugin(src)` — Apply the Plugin in `android/app/build.gradle`

Inserts `apply plugin: 'com.spotify.ruler'` immediately after the `apply plugin: "com.facebook.react"` line in the app-level `build.gradle`. This ordering ensures React Native is initialized before Ruler hooks into the build.

```typescript
import { addRulerApplyPlugin } from "expo-ruler/build/withRuler";

const appGradle = `
apply plugin: "com.android.application"
apply plugin: "org.jetbrains.kotlin.android"
apply plugin: "com.facebook.react"

android {
    compileSdkVersion 34
}
`;

const patched = addRulerApplyPlugin(appGradle);
console.log(patched);
/*
apply plugin: "com.android.application"
apply plugin: "org.jetbrains.kotlin.android"
apply plugin: "com.facebook.react"
// @generated begin expo-ruler-apply-plugin - expo prebuild (DO NOT MODIFY)
apply plugin: 'com.spotify.ruler'
// @generated end expo-ruler-apply-plugin

android {
    compileSdkVersion 34
}
*/

// Idempotency guaranteed
const twice = addRulerApplyPlugin(patched);
console.log(twice === patched); // true
```
```

--------------------------------

### Configure expo-ruler in app.json

Source: https://github.com/shubh73/expo-ruler/blob/main/README.md

Add the expo-ruler plugin to your app.json configuration file.

```json
{
  "expo": {
    "plugins": ["expo-ruler"]
  }
}
```

--------------------------------

### Handle invalid ABI with withRuler

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Shows how `withRuler` validates the ABI option and lists allowed values when an invalid one is provided.

```typescript
// Invalid ABI → throws with allowed values listed
withRuler(config, { abi: "mips" as any });
// Error: expo-ruler: invalid abi "mips". Allowed values: arm64-v8a, armeabi-v7a, x86, x86_64.
```

--------------------------------

### RulerPluginProps Type Reference

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Defines the configuration options for the Ruler plugin. All fields are optional; omitted fields fall back to the built-in defaults.

```typescript
import type { RulerPluginProps } from "expo-ruler/build/withRuler";

// All fields with their defaults shown explicitly
const options: RulerPluginProps = {
  abi: "arm64-v8a",      // "arm64-v8a" | "armeabi-v7a" | "x86" | "x86_64"
  locale: "en",          // any BCP 47 locale string
  screenDensity: 480,    // dpi as a finite number (e.g. 160, 240, 320, 480, 560)
  sdkVersion: 36,        // Android API level as an integer
  rulerVersion: "2.0.0-beta-3", // any valid Ruler release string
};
```

--------------------------------

### RulerPluginProps Type Reference

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Type reference for `RulerPluginProps`, detailing the optional configuration properties for the Ruler plugin.

```APIDOC
## `RulerPluginProps` — Type Reference

All fields are optional; omitted fields fall back to the built-in defaults.

```typescript
import type { RulerPluginProps } from "expo-ruler/build/withRuler";

// All fields with their defaults shown explicitly
const options: RulerPluginProps = {
  abi: "arm64-v8a",      // "arm64-v8a" | "armeabi-v7a" | "x86" | "x86_64"
  locale: "en",          // any BCP 47 locale string
  screenDensity: 480,    // dpi as a finite number (e.g. 160, 240, 320, 480, 560)
  sdkVersion: 36,        // Android API level as an integer
  rulerVersion: "2.0.0-beta-3", // any valid Ruler release string
};
```
```

--------------------------------

### Insert Ruler Extension Block in build.gradle

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Inserts the `ruler { }` Groovy extension block directly above the `android { }` block in `android/app/build.gradle`. Accepts `abi`, `locale`, `screenDensity`, and `sdkVersion`. When any prop value changes, the existing generated block is replaced with the updated values. The function is idempotent.

```typescript
import { addRulerExtensionBlock } from "expo-ruler/build/withRuler";

const appGradle = `
apply plugin: "com.facebook.react"

android {
    compileSdkVersion 34
    defaultConfig {
        applicationId 'com.example.app'
    }
}
`;

// Default device profile (modern ARM64 high-density)
const patched = addRulerExtensionBlock(appGradle, {
  abi: "arm64-v8a",
  locale: "en",
  screenDensity: 480,
  sdkVersion: 36,
});
console.log(patched);
/*
apply plugin: "com.facebook.react"

// @generated begin expo-ruler-extension-block - expo prebuild (DO NOT MODIFY)
ruler {
    abi = "arm64-v8a"
    locale = "en"
    screenDensity = 480
    sdkVersion = 36
}

// @generated end expo-ruler-extension-block
android {
    compileSdkVersion 34
    ...
}
*/

// Changing locale and screenDensity replaces the block in-place
const updated = addRulerExtensionBlock(patched, {
  abi: "arm64-v8a",
  locale: "de",
  screenDensity: 320,
  sdkVersion: 36,
});
console.log(updated.includes(`locale = "de"`));       // true
console.log(updated.includes(`screenDensity = 320`)); // true
console.log(updated.includes(`locale = "en"`));       // false
```

--------------------------------

### addRulerExtensionBlock(src, props)

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Inserts the `ruler { }` Groovy extension block above the `android { }` block in `android/app/build.gradle`. This function accepts configuration properties like `abi`, `locale`, `screenDensity`, and `sdkVersion`.

```APIDOC
## `addRulerExtensionBlock(src, props)` — Insert `ruler { }` Configuration

Inserts the `ruler { }` Groovy extension block directly above the `android { }` block in `android/app/build.gradle`. Accepts `abi`, `locale`, `screenDensity`, and `sdkVersion`. When any prop value changes, the existing generated block is replaced with the updated values.

```typescript
import { addRulerExtensionBlock } from "expo-ruler/build/withRuler";

const appGradle = `
apply plugin: "com.facebook.react"

android {
    compileSdkVersion 34
    defaultConfig {
        applicationId 'com.example.app'
    }
}
`;

// Default device profile (modern ARM64 high-density)
const patched = addRulerExtensionBlock(appGradle, {
  abi: "arm64-v8a",
  locale: "en",
  screenDensity: 480,
  sdkVersion: 36,
});
console.log(patched);
/*
apply plugin: "com.facebook.react"

// @generated begin expo-ruler-extension-block - expo prebuild (DO NOT MODIFY)
ruler {
    abi = "arm64-v8a"
    locale = "en"
    screenDensity = 480
    sdkVersion = 36
}

// @generated end expo-ruler-extension-block
android {
    compileSdkVersion 34
    ...
}
*/

// Changing locale and screenDensity replaces the block in-place
const updated = addRulerExtensionBlock(patched, {
  abi: "arm64-v8a",
  locale: "de",
  screenDensity: 320,
  sdkVersion: 36,
});
console.log(updated.includes(`locale = "de"`));       // true
console.log(updated.includes(`screenDensity = 320`)); // true
console.log(updated.includes(`locale = "en"`));       // false
```
```

--------------------------------

### Programmatic usage of withRuler in dynamic config

Source: https://context7.com/shubh73/expo-ruler/llms.txt

Use the `withRuler` plugin programmatically in a dynamic Expo config file (e.g., `app.config.ts`) with custom options.

```typescript
import withRuler from "expo-ruler";
import type { ExpoConfig } from "expo/config";

// Programmatic usage inside a dynamic config (app.config.ts)
const config: ExpoConfig = {
  name: "MyApp",
  slug: "my-app",
};

export default withRuler(config, {
  abi: "arm64-v8a",
  locale: "en",
  screenDensity: 480,
  sdkVersion: 36,
  rulerVersion: "2.0.0-beta-3",
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.