zipy-mobile-cli

<<<<<<< HEAD CLI to integrate Zipy with mobile apps. When you build your app, it uploads Android sourcemaps/bundles and iOS dSYMs so Zipy can symbolicate errors.

CLI to integrate Zipy with mobile apps. When you build your app (e.g. React Native Android), it uploads sourcemaps so Zipy can symbolicate errors.

origin/main

Install

Recommended (for Gradle apply-from): add as a devDependency in your React Native project so require.resolve('zipy-mobile-cli/package.json') finds it when Gradle runs:

npm install zipy-mobile-cli --save-dev

Then run init with npx zipy-mobile-cli -i react-native.

Alternatively, install globally:

npm install -g zipy-mobile-cli

If you install globally, the init still adds the same apply from: ... zipy.gradle line; Gradle will resolve the package from node_modules when building, so you should also have zipy-mobile-cli as a devDependency for the apply to work.

Usage

1. Initialize in your React Native project

From your React Native project root (where package.json and android/ live):

zipy-mobile-cli -i react-native

or:

zipy-mobile-cli init react-native

This will:

• Ask for the path to your sourcemaps (with sensible defaults):
  • Release: android/app/build/generated/sourcemaps/react/release/index.android.bundle.map
  • Debug: android/app/build/generated/sourcemaps/react/debug/index.android.bundle.map
• Create a config file .zipy-mobile.json in the project root with those paths.
• Add an apply from: line to android/app/build.gradle that applies zipy.gradle. That script hooks into react/release (the task that bundles JS and generates the source map). When that task finishes, it runs npx zipy-mobile-cli upload-sourcemaps release; the paths in .zipy-mobile.json match this task’s outputs. Debug is not hooked.
• Add an iOS Run Script Build Phase named ZipySourcemapsUpload that detects the generated .dSYM from Xcode build variables and uploads it automatically on each build/run.

So whenever a new build is made, Android sourcemaps or iOS dSYMs are uploaded automatically; you don’t need to run a separate command.

2. Configure upload (from init)

Init prompts for (or use env): Upload API base URL, API key, Customer ID, Framework. These are stored in .zipy-mobile.json and used to call:

POST {uploadBaseUrl}/v1/upload/{apiKey}/{customerId} with multipart form: bundle_id, release_version, framework, platform, files. When the upload runs from gradlew assembleRelease, platform is set to android and bundle_id/release_version come from the build.

3. Build as usual

From project root:

cd android && ./gradlew assembleRelease

or:

./gradlew -p android assembleRelease

After the build finishes, the CLI will upload the sourcemap for that variant.

4. Zipy bundle id (release builds)

Each release build generates a new Zipy bundle id (UUID) when the source map is new or changed, injects it into the release (and packager) source map files under zipyBundleId / zipy_bundle_id, then uploads. No extra folder or assets are created; the ID lives only in the map files and in the upload payload.

• When it runs: The inject task uses the source map as input, so it re-runs whenever the bundle produces a new or changed map (e.g. after code changes). You get a new ID for each such build.
• BuildConfig.ZIPY_BUNDLE_ID is still set to the application ID for use in the app.

Config file (.zipy-mobile.json)

Example (created by init; API key and customer ID are set at init):

{
  "projectRoot": "/path/to/your/rn-app",
  "framework": "react-native",
  "uploadBaseUrl": "http://localhost:8900",
  "apiKey": "abc123key",
  "customerId": "99",
  "sourcemaps": {
    "android": {
      "release": "android/app/build/generated/sourcemaps/react/release/index.android.bundle.map",
      "debug": "android/app/build/generated/sourcemaps/react/debug/index.android.bundle.map"
    }
  },
  "bundle": {
    "android": {
      "release": "android/app/build/generated/assets/react/release/index.android.bundle"
    }
  },
  "dsym": {
    "ios": {}
  }
}

Upload is sent as: POST {uploadBaseUrl}/sourcemaps-mobile-service//v1/upload/{apiKey}/{customerId} with form fields bundle_id, release_version, framework, platform, and files. Android uploads the sourcemap plus bundle when present; iOS uploads the build dSYM and archives the .dSYM bundle to .zip automatically before sending it.

Manual upload

You can also trigger upload manually (e.g. for CI):

zipy-mobile-cli upload-sourcemaps release
zipy-mobile-cli upload-sourcemaps debug

Run this from the project root (or any directory under it that has .zipy-mobile.json above it).

For manual iOS uploads, pass the dSYM path and platform explicitly:

ZIPY_PLATFORM=ios ZIPY_DSYM_PATH=/path/to/MyApp.app.dSYM npx zipy-mobile-cli upload-sourcemaps release

Requirements

• Node.js >= 14
• React Native project with Android (android/app/build.gradle).
• macOS/Xcode for iOS dSYM auto-upload (ditto is used to archive the .dSYM bundle before upload).
• zipy-mobile-cli either as a project devDependency or installed globally (npm install -g zipy-mobile-cli). Gradle resolves zipy.gradle from node_modules first, then from global npm root.

Command to add in your RN app (manual)

If you prefer to add the Zipy Gradle integration by hand, add this at the end of android/app/build.gradle (after the android and dependencies blocks):

def zipyProjectRoot = project.rootProject.projectDir.parentFile
def zipyGradleFile = null
try {
  def zipyPackageJson = ["node", "--print", "require.resolve('zipy-mobile-cli/package.json')"].execute(null, zipyProjectRoot).text.trim()
  if (zipyPackageJson) {
    def dir = new File(zipyPackageJson).parentFile
    if (dir != null) zipyGradleFile = new File(dir, "zipy.gradle")
  }
} catch (Throwable ignored) {}
if (zipyGradleFile == null || !zipyGradleFile.exists()) {
  def npmGlobalRoot = ["npm", "root", "-g"].execute(null, zipyProjectRoot).text.trim()
  if (npmGlobalRoot) zipyGradleFile = new File(npmGlobalRoot, "zipy-mobile-cli/zipy.gradle")
}
if (zipyGradleFile != null && zipyGradleFile.exists()) {
  apply from: zipyGradleFile
}

This resolves zipy.gradle from project node_modules (if zipy-mobile-cli is a devDependency) or from global install (npm root -g + zipy-mobile-cli). It then applies zipy.gradle, which:

• Hooks into release bundle tasks (createBundle*JsAndAssets, non-debug)
• For each such task: registers ZipyUpload (runs npx zipy-mobile-cli upload-sourcemaps release with ZIPY_RELEASE, ZIPY_DIST, ZIPY_BUILD_ID from the build) and ZipyCleanup
• Chain: bundle task → ZipyUpload → ZipyCleanup

Set ZIPY_DISABLE_AUTO_UPLOAD=true in the environment to skip upload (e.g. for local builds).

Uninstall / remove integration

1. Remove the apply from: ... zipy.gradle line from android/app/build.gradle (search for zipy-mobile-cli).
2. Delete .zipy-mobile.json.
3. Optionally: npm uninstall zipy-mobile-cli (or npm uninstall -g zipy-mobile-cli if you installed globally).