View and edit Android on-device preferences: NO ROOT required! 🥳

Both legacy shared preferences and Preference Datastore are supported! 😎

• Android adb server
• Node.js (see .nvmrc for compatible version)

Install the package:

npm i @charlesmuchene/pref-editor

You can override ADB connection settings with environment variables:

export PREF_EDITOR_ADB_HOST=localhost
export PREF_EDITOR_ADB_PORT=5037
export PREF_EDITOR_WATCHER_INTERVAL_MS=3000  # Max 180000 (3 minutes)

import {
    Preference,
    TypeTag,
    changePreference,
    watchPreference,
} from "@charlesmuchene/pref-editor";

const connection = {
    deviceId: "emulator-5554",
    appId: "com.charlesmuchene.datastore",
    filename: "settings.preferences_pb",
};

// Change a preference
const pref: Preference = {
    key: "isVisited",
    value: "false",
    type: TypeTag.BOOLEAN,
};

await changePreference(pref, connection);

// Watch for preference changes (NEW: EventEmitter pattern)
const watch = await watchPreference({ key: "isVisited" }, connection);

watch.emitter.on("change", (newValue, preference) => {
    console.log(`Preference changed: ${preference.key} = ${newValue}`);
});

watch.emitter.on("error", (error) => {
    console.error("Watch error:", error);
});

// Clean up when done
watch.close();

See the Android Preferences Editor MCP server project for comprehensive usage examples.

• string-set key-value preference type operations are partially supported

# Clone the repository
git clone https://github.com/charlesmuchene/pref-editor-js.git
cd pref-editor-js

# Install dependencies
npm install

# Run verification (lint, build, test, coverage)
npm run verify

For detailed development setup and workflow, see DEV.md.

We welcome contributions! Please see:

• CONTRIBUTING.md - Contribution guidelines
• DEV.md - Development setup and workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Make your changes and add tests
4. Run verification: npm run verify
5. Submit a pull request with title format: feat:, fix:, or BREAKING:

See LICENSE

• 📖 Documentation: DEV.md for development setup
• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues
• 🤝 Contributing: CONTRIBUTING.md

• BREAKING: watchPreference now uses EventEmitter pattern instead of streams
• NEW: Added 3-minute maximum limit for watch intervals
• IMPROVED: Better error handling and event management

See releases for full changelog.