Skip to content

Installation

rosetta-frida runs inside a Frida script (authored in TypeScript or JavaScript and compiled with frida-compile) and provides a CLI, rosetta, for map authoring and bundle manipulation.

Install (npm)

Availability: the npm package becomes available with the first tagged release (v*). Until that lands, install by building from source (see below) — that is the working path today.

Once the first release is published, install it from npm:

npm install rosetta-frida

This pulls the runtime library and the rosetta CLI (run it with npx rosetta <command>). Releases are tag-driven: pushing a v* version tag triggers the release workflow, which rebuilds, re-runs the 100% coverage gate, and publishes with npm provenance, so a published version always corresponds to a green build.

Requirements

  • Node.js 24 or newer (build/CLI side only — see engines.node in package.json). The compiled hook itself runs in Frida's JS sandbox like any other Frida script. Older Node versions are unsupported.
  • Frida 16 or newer in the target environment (frida-server on the device, plus whichever controller you use — Python frida, frida CLI, frida-node). The library is tested against Frida 16 and 17.
  • frida-compile 16+ for compiling TypeScript or modern JavaScript hooks into a single bundle Frida can load.

There is no Python, Java, or Android-SDK dependency on the host running rosetta-frida. The CLI is pure Node; the runtime is pure JS that loads inside Frida's Quickjs / V8 sandbox.

Install (clone & build from source)

Prefer to work against the source tree (e.g. to contribute)? Clone the repo and build it:

git clone https://github.com/Xiddoc/rosetta-frida
cd rosetta-frida
npm install
npm run build

This gives you:

  • The runtime library (compiled into dist/), importable from a local checkout or via a path/npm link reference.
  • The rosetta CLI, run via npm run cli -- <command> from the repo root.

Dependencies

rosetta-frida itself depends only on yaml (for the YAML converter) and zod (for schema validation); npm install pulls both. There are no peer dependencies to install yourself.

You do need frida-compile to compile hooks. It is the standard build step for any non-trivial Frida script:

npm install --save-dev frida-compile

Verify the install

npm run cli -- --help

You should see:

Usage: rosetta <command> [options]

Commands:
  init <app> <version>                 Scaffold a new map skeleton
  validate <map>                       Schema + sanity check (auto-detect format)
  convert <in> -o <out>                Convert YAML map to canonical JSON
  patch <bundle.js> --map <new.json>   Replace embedded map in bundle
  extract <bundle.js> -o <out.json>    Pull embedded map out of bundle
  inspect <bundle.js>                  One-line summary of embedded map

TypeScript types

The package ships its own .d.ts declarations — no separate @types/rosetta-frida package needed.

If you author hooks in TypeScript, add Frida's types so the global Java, send, and Interceptor symbols resolve:

npm install --save-dev @types/frida-gum

Then in tsconfig.json:

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "moduleResolution": "Bundler",
        "types": ["frida-gum"],
        "resolveJsonModule": true
    }
}

resolveJsonModule is required for import map from './x.json' to work — that is how maps reach your hook source.

Next steps

  • Quick start — the smallest end-to-end hook.
  • Concepts — real vs obfuscated names, the rotation problem, sessions, marker block.
  • Authoring maps — how to write a map for a new app or version.