Migration from v1.x

Version 2.0 is a complete rewrite with breaking changes. This guide will help you migrate from v1.x to v2.x.

Breaking Changes

ESM Only

v2.0 is ESM-only. CommonJS is no longer supported.

Before (v1.x):

// CommonJS
const Apk = require("node-apk").default;
// or
const { Apk } = require("node-apk");

After (v2.x):

// ESM
import { Apk } from "node-apk";

Required package.json change:

{
  "type": "module"
}

Named Exports Only

The default export has been removed. Use named exports only.

Before (v1.x):

import Apk from "node-apk";

After (v2.x):

import { Apk } from "node-apk";

Async/Await API

All methods now properly support async/await. Promise chains still work but async/await is preferred.

Before (v1.x):

apk.getManifestInfo().then((manifest) => {
  console.log(manifest.package);
});

After (v2.x):

const manifest = await apk.getManifestInfo();
console.log(manifest.package);

Removed close() Method

The close() method has been removed as it was a no-op.

Before (v1.x):

const apk = new Apk("app.apk");
// ... use apk
apk.close(); // Did nothing

After (v2.x):

const apk = new Apk("app.apk");
// ... use apk
// No cleanup needed

Node.js Version Requirement

v2.0 requires Node.js 20 or later.

Version	Node.js Requirement
v1.x	Node.js 12+
v2.x	Node.js 20+

New Features

getLabel()

New helper method to resolve app labels with locale support:

// Get default label
const label = await apk.getLabel();

// Get localized label
const label = await apk.getLabel({ locale: "fr" });

getLauncherIcon()

New helper method to extract launcher icons:

// Get best available icon
const icon = await apk.getLauncherIcon();

// Get specific density
const icon = await apk.getLauncherIcon({ density: "xhdpi" });

Migration Checklist

• [ ] Update Node.js to version 20 or later
• [ ] Add "type": "module" to your package.json
• [ ] Replace default imports with named imports
• [ ] Convert .js files to .mjs or update to ESM syntax
• [ ] Update TypeScript config for ESM support
• [ ] Remove any apk.close() calls
• [ ] Update to async/await pattern (recommended)

Complete Migration Example

v1.x Code

// CommonJS syntax
import Apk from "node-apk";

async function parseApk(path: string) {
  const apk = new Apk(path);
  
  apk.getManifestInfo().then((manifest) => {
    console.log("Package:", manifest.package);
  });
  
  apk.getResources().then((resources) => {
    // Manual label resolution
    const labelId = manifest.applicationLabel;
    const resolved = resources.resolve(labelId);
    const label = resolved[0]?.value;
    console.log("Label:", label);
  });
  
  apk.close();
}

v2.x Code

// ESM syntax
import { Apk } from "node-apk";

async function parseApk(path: string) {
  const apk = new Apk(path);
  
  const manifest = await apk.getManifestInfo();
  console.log("Package:", manifest.package);
  
  // Using new helper method
  const label = await apk.getLabel();
  console.log("Label:", label);
  
  // No close() needed
}

Type Changes

ResourceValue

The ResourceValue type is now more explicit:

// v2.x
type ResourceValue = number | string | boolean | null;

New Types

Several new utility types are available:

import {
  LabelOptions,
  IconOptions,
  IconDensity,
  Locale,
} from "node-apk";

Troubleshooting

"Cannot use import statement outside a module"

Add "type": "module" to your package.json and use .mjs extension or ESM syntax.

"require() of ES Module not supported"

Switch to ESM imports. CommonJS require() is not supported.

Type errors after upgrade

Update your TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Need Help?

If you encounter issues during migration:

1. Check the API Reference for updated method signatures
2. Review the Examples for usage patterns
3. Open an issue on GitHub