DEV Community: Amit Kumar

🚨 npm Vulnerabilities Are Growing — A Practical Defense Using OSV.dev in React Native

Amit Kumar — Mon, 06 Apr 2026 09:11:50 +0000

As we know, npm packages are getting hacked day by day.

From malicious package injections to supply chain attacks, dependency management is no longer just about keeping things updated — it’s about security, visibility, and control.

So I built a Smart Dependency Report System that gives complete visibility into your dependencies.

🧩 The Real Problem Isn’t Dependencies — It’s Visibility

Most developers rely on:

npm outdated
npm audit

But let’s be honest—these tools are:

❌ Noisy
❌ Hard to prioritize
❌ Not decision-friendly

They tell you everything, but help you decide nothing.

You don’t need a list.
You need clarity.

🧠 What This System Does

Classifies updates (Major / Minor / Patch)
Detects vulnerabilities via OSV.dev
Fetches npm metadata (size, publish date)
Handles git/file/workspace dependencies
Generates CLI + PDF reports
Provides actionable recommendations

📊 Output

Terminal View

PDF View

📦 Installation & Setup

To get started with the Smart Dependency Report System, install the required dependencies:


yarn add --dev chalk cli-table3 semver pdfkit

Note:

Please update this path based on the location where you’ve placed the dependency-report folder.

/** Repo root (directory that contains package.json). */
const PROJECT_ROOT = path.resolve(__dirname, '..', '..', '..', '..');

📁 Project Structure

src/
└── config/
    └── scripts/
        └── dependency-report/
            ├── analyzeVersions.js
            ├── badges.js
            ├── constants.js
            ├── generate-report.js
            ├── npmAuditSecurity.js
            ├── npmRegistry.js
            ├── osvSecurity.js
            ├── readPackages.js
            ├── reportConsole.js
            ├── reportPdf.js
            ├── reportSummary.js
            └── runReport.js

⚙️ Code Walkthrough (File by File)

📄 `generate-report.js` (Entry Point)

#!/usr/bin/env node
/**
 * React Native dependency report: compares installed versions to npm "latest",
 * prints a CLI table, and writes report/dependency-report.pdf under the project root.
 *
 * Usage:
 *   npm run report:deps
 *   node src/config/scripts/dependency-report/generate-report.js
 *   node src/config/scripts/dependency-report/generate-report.js --major-only
 *   node src/config/scripts/dependency-report/generate-report.js --sort=update-type
 *
 * Security: vulnerabilities come from OSV.dev (https://api.osv.dev) using package-lock.json
 * when present, otherwise installed versions from node_modules for direct dependencies.
 *
 * Optional env:
 *   DEPENDENCY_REPORT_OSV_API=https://api.osv.dev   (override OSV API base URL)
 *   DEPENDENCY_REPORT_OSV_TIMEOUT_MS=120000       (HTTP timeout for OSV calls)
 *   REPORT_SKIP_AUDIT=1                           (skip OSV; Secure column shows unknown)
 *   DEPENDENCY_REPORT_SECURE_ICON_URL=...        (PDF secure-cell image, optional)
 */

const path = require('path');
const { run } = require('./runReport');

/** Repo root (directory that contains package.json). */
const PROJECT_ROOT = path.resolve(__dirname, '..', '..', '..', '..');

function printHelp() {
  console.log(`
React Native Dependency Report

Usage:
  npm run report:deps
  node src/config/scripts/dependency-report/generate-report.js [options]

Options:
  --major-only          Only include packages with a semver MAJOR update available
  --sort=update-type    Sort by update severity (Major → Minor → Patch → …), then name
  --sort=name           Sort alphabetically by package name (default)
  --help, -h            Show this help

Outputs:
  - Table printed to stdout
  - report/dependency-report.pdf (project root)

Environment:
  DEPENDENCY_REPORT_OSV_API           OSV API base (default: https://api.osv.dev)
  DEPENDENCY_REPORT_OSV_TIMEOUT_MS    Timeout ms for OSV HTTP requests (default: 120000)
  REPORT_SKIP_AUDIT                   Set to 1 to skip OSV and mark Secure as unknown
  DEPENDENCY_REPORT_SECURE_ICON_URL   Optional HTTPS URL to PNG/JPEG for the PDF secure cell
`);
}

/**
 * @param {string[]} argv
 */
function parseArgs(argv) {
  const opts = {
    majorOnly: false,
    sort: /** @type {'name' | 'update-type'} */ ('name'),
  };

  for (let i = 2; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--help' || arg === '-h') {
      return { ...opts, help: true };
    }
    if (arg === '--major-only') {
      opts.majorOnly = true;
      continue;
    }
    if (arg.startsWith('--sort=')) {
      const v = arg.slice('--sort='.length).toLowerCase();
      if (v === 'update-type' || v === 'type') {
        opts.sort = 'update-type';
      } else if (v === 'name' || v === 'package') {
        opts.sort = 'name';
      } else {
        console.warn(`Unknown --sort value "${v}", using name.`);
        opts.sort = 'name';
      }
      continue;
    }
    console.warn(`Ignoring unknown argument: ${arg}`);
  }

  return { ...opts, help: false };
}

async function main() {
  const parsed = parseArgs(process.argv);
  if (parsed.help) {
    printHelp();
    process.exit(0);
  }

  try {
    const { pdfPath } = await run(PROJECT_ROOT, {
      majorOnly: parsed.majorOnly,
      sort: parsed.sort,
    });
    console.log(`\nPDF written to: ${pdfPath}`);
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    console.error('Dependency report failed:', message);
    process.exitCode = 1;
  }
}

main();

👉 This is the CLI entry point that triggers everything.

📄 `runReport.js` (Core Orchestrator)


/**
 * Orchestrates reading package.json, querying npm, sorting/filtering, and rendering outputs.
 */

const fs = require('fs');
const path = require('path');
const {
  collectDeclaredPackages,
  readInstalledVersion,
} = require('./readPackages');
const { fetchPackageMeta } = require('./npmRegistry');
const {
  classifyUpdateType,
  describeNonRegistryRow,
} = require('./analyzeVersions');
const { UPDATE_TYPE, UPDATE_TYPE_SORT_ORDER } = require('./constants');
const { attachSecurityFromOsv } = require('./osvSecurity');
const { printConsoleTable, printConsoleSummary } = require('./reportConsole');
const { writePdfReport } = require('./reportPdf');

/**
 * @typedef {object} ReportRow
 * @property {string} name
 * @property {'dependencies'|'devDependencies'} kind
 * @property {string} wantedRange
 * @property {string | null} installedVersion
 * @property {string | null} latestVersion
 * @property {string | null} lastPublished
 * @property {number | null} unpackedSizeBytes
 * @property {string} updateType
 * @property {string | null} [registryError]
 * @property {'none'|'info'|'low'|'moderate'|'high'|'critical'|'unknown'} [securityLevel]
 * @property {number} [securityCount]
 * @property {string} [securityTooltip]
 */

/**
 * Run async work in chunks to limit concurrent registry calls.
 * @template T, R
 * @param {T[]} items
 * @param {number} limit
 * @param {(item: T, index: number) => Promise<R>} fn
 * @returns {Promise<R[]>}
 */
async function mapPool(items, limit, fn) {
  const results = new Array(items.length);
  let i = 0;
  const workers = new Array(Math.min(limit, items.length)).fill(0).map(async () => {
    while (i < items.length) {
      const idx = i++;
      results[idx] = await fn(items[idx], idx);
    }
  });
  await Promise.all(workers);
  return results;
}

/**
 * @param {string} projectRoot
 * @param {{ majorOnly?: boolean, sort?: 'name' | 'update-type', pdfPath?: string, concurrency?: number }} options
 * @returns {Promise<{ rows: ReportRow[], pdfPath: string }>}
 */
async function run(projectRoot, options = {}) {
  const {
    majorOnly = false,
    sort = 'name',
    pdfPath = path.join(projectRoot, 'report', 'dependency-report.pdf'),
    concurrency = 12,
  } = options;

  const declared = collectDeclaredPackages(projectRoot);

  /** @type {ReportRow[]} */
  const rows = await mapPool(declared, concurrency, async (entry) => {
    const installed = readInstalledVersion(projectRoot, entry.name);
    const { skipRegistry, note } = describeNonRegistryRow(entry.wantedRange);

    if (skipRegistry) {
      return {
        name: entry.name,
        kind: entry.kind,
        wantedRange: entry.wantedRange,
        installedVersion: installed,
        latestVersion: null,
        lastPublished: null,
        unpackedSizeBytes: null,
        updateType: UPDATE_TYPE.UNKNOWN,
        registryError: note,
      };
    }

    const meta = await fetchPackageMeta(entry.name);
    const latest = meta.latestVersion;
    let updateType = UPDATE_TYPE.UNKNOWN;

    if (latest) {
      updateType = classifyUpdateType(installed, latest);
    } else if (meta.error) {
      updateType = UPDATE_TYPE.UNKNOWN;
    }

    return {
      name: entry.name,
      kind: entry.kind,
      wantedRange: entry.wantedRange,
      installedVersion: installed,
      latestVersion: latest,
      lastPublished: meta.lastPublished,
      unpackedSizeBytes: meta.unpackedSizeBytes,
      updateType,
      registryError: meta.error,
    };
  });

  if (process.env.REPORT_SKIP_AUDIT === '1') {
    for (const row of rows) {
      row.securityLevel = 'unknown';
      row.securityCount = 0;
      row.securityTooltip = 'Skipped OSV (REPORT_SKIP_AUDIT=1)';
    }
  } else {
    await attachSecurityFromOsv(projectRoot, rows);
  }

  let filtered = rows;
  if (majorOnly) {
    filtered = rows.filter((r) => r.updateType === UPDATE_TYPE.MAJOR);
  }

  const sorted = [...filtered].sort((a, b) => {
    if (sort === 'update-type') {
      const oa =
        UPDATE_TYPE_SORT_ORDER[a.updateType] ?? UPDATE_TYPE_SORT_ORDER[UPDATE_TYPE.UNKNOWN];
      const ob =
        UPDATE_TYPE_SORT_ORDER[b.updateType] ?? UPDATE_TYPE_SORT_ORDER[UPDATE_TYPE.UNKNOWN];
      if (oa !== ob) {
        return oa - ob;
      }
    }
    return a.name.localeCompare(b.name, 'en');
  });

  printConsoleTable(sorted);
  printConsoleSummary(sorted);

  const flagged = sorted.filter((r) => r.registryError);
  if (flagged.length > 0) {
    console.warn(
      `\nNote: ${flagged.length} package(s) have registry/spec limitations (git/file/link or fetch errors).`,
    );
  }

  fs.mkdirSync(path.dirname(pdfPath), { recursive: true });
  await writePdfReport(pdfPath, sorted);

  return { rows: sorted, pdfPath };
}

module.exports = { run, mapPool };

👉 This file:

Reads dependencies
Fetches registry data
Classifies updates
Attaches security
Generates output

📄 `readPackages.js` (Dependency Reader)


/**
 * Load dependencies from package.json and resolve installed versions from node_modules.
 */

const fs = require('fs');
const path = require('path');

/**
 * @param {string} projectRoot
 * @returns {{ name: string, wantedRange: string, kind: 'dependencies' | 'devDependencies' }[]}
 */
function collectDeclaredPackages(projectRoot) {
  const pkgPath = path.join(projectRoot, 'package.json');
  const raw = fs.readFileSync(pkgPath, 'utf8');
  const pkg = JSON.parse(raw);

  const out = [];

  const deps = pkg.dependencies || {};
  for (const [name, wantedRange] of Object.entries(deps)) {
    out.push({
      name,
      wantedRange: String(wantedRange),
      kind: 'dependencies',
    });
  }

  const devDeps = pkg.devDependencies || {};
  for (const [name, wantedRange] of Object.entries(devDeps)) {
    out.push({
      name,
      wantedRange: String(wantedRange),
      kind: 'devDependencies',
    });
  }

  return out;
}

/**
 * Read version from node_modules/<name>/package.json (supports scoped names).
 * @param {string} projectRoot
 * @param {string} packageName
 * @returns {string | null}
 */
function readInstalledVersion(projectRoot, packageName) {
  const parts = packageName.startsWith('@')
    ? packageName.split('/')
    : [packageName];
  const rel =
    parts.length === 2
      ? path.join('node_modules', parts[0], parts[1])
      : path.join('node_modules', parts[0]);
  const installedPkgPath = path.join(projectRoot, rel, 'package.json');

  try {
    const data = JSON.parse(fs.readFileSync(installedPkgPath, 'utf8'));
    return typeof data.version === 'string' ? data.version : null;
  } catch {
    return null;
  }
}

/**
 * Heuristic: npm registry cannot resolve arbitrary git/file/tar URLs as "latest" the same way.
 * @param {string} range
 */
function isNonRegistrySpec(range) {
  return (
    /^(file:|git\+|git:|github:|https?:\/\/|link:|workspace:|workspace:\*)/i.test(
      range.trim(),
    ) || range.includes('/')
  );
}

module.exports = {
  collectDeclaredPackages,
  readInstalledVersion,
  isNonRegistrySpec,
};

👉 Extracts both declared and installed versions.

📄 `npmRegistry.js` (Registry Fetcher)


/**
 * Fetch package metadata from the public npm registry (using axios).
 */

const axios = require('axios');

const REGISTRY_BASE = 'https://registry.npmjs.org';
const REQUEST_TIMEOUT_MS = 25_000;

/**
 * @typedef {object} RegistryMeta
 * @property {string | null} latestVersion
 * @property {string | null} lastPublished
 * @property {number | null} unpackedSizeBytes
 * @property {string | null} error
 */

/**
 * @param {string} packageName
 * @returns {Promise<RegistryMeta>}
 */
async function fetchPackageMeta(packageName) {
  // Scoped names: encode @ and / per npm registry (e.g. @babel/core -> %40babel%2Fcore)
  const url = `${REGISTRY_BASE}/${encodeURIComponent(packageName)}`;

  try {
    const { data } = await axios.get(url, {
      timeout: REQUEST_TIMEOUT_MS,
      headers: { Accept: 'application/json' },
      // Full document is needed for versions[ver].dist and time
      validateStatus: (s) => s === 200 || s === 404,
    });

    if (data == null || data.error || !data['dist-tags']) {
      return {
        latestVersion: null,
        lastPublished: null,
        unpackedSizeBytes: null,
        error: data?.error || 'Not found or invalid registry response',
      };
    }

    const latest = data['dist-tags']?.latest;
    if (!latest || typeof latest !== 'string') {
      return {
        latestVersion: null,
        lastPublished: null,
        unpackedSizeBytes: null,
        error: 'No dist-tags.latest',
      };
    }

    const timeMap = data.time || {};
    const lastPublished =
      typeof timeMap[latest] === 'string' ? timeMap[latest] : null;

    const verInfo = data.versions?.[latest];
    const unpacked =
      verInfo?.dist && typeof verInfo.dist.unpackedSize === 'number'
        ? verInfo.dist.unpackedSize
        : null;

    return {
      latestVersion: latest,
      lastPublished,
      unpackedSizeBytes: unpacked,
      error: null,
    };
  } catch (err) {
    const message =
      err.response?.status === 404
        ? 'Package not found on registry'
        : err.message || String(err);
    return {
      latestVersion: null,
      lastPublished: null,
      unpackedSizeBytes: null,
      error: message,
    };
  }
}

module.exports = { fetchPackageMeta, REGISTRY_BASE };

👉 Fetches:

Latest version
Publish date
Package size

📄 `analyzeVersions.js` (Version Intelligence)


/**
 * Compare installed vs latest using semver and classify update type.
 */

const semver = require('semver');
const { UPDATE_TYPE } = require('./constants');
const { isNonRegistrySpec } = require('./readPackages');

/**
 * @param {string | null} installed
 * @param {string | null} latest
 * @returns {typeof UPDATE_TYPE[keyof typeof UPDATE_TYPE]}
 */
function classifyUpdateType(installed, latest) {
  if (!latest) {
    return UPDATE_TYPE.UNKNOWN;
  }
  if (!installed || !semver.valid(installed)) {
    return UPDATE_TYPE.UNKNOWN;
  }
  if (!semver.valid(latest)) {
    return UPDATE_TYPE.UNKNOWN;
  }

  if (semver.eq(installed, latest)) {
    return UPDATE_TYPE.UP_TO_DATE;
  }

  // If "latest" is not actually newer (e.g. user on newer prerelease), treat as unknown edge case
  if (!semver.gt(latest, installed)) {
    const pre = semver.prerelease(installed);
    if (pre && semver.eq(semver.coerce(installed), semver.coerce(latest))) {
      return UPDATE_TYPE.PRERELEASE;
    }
    return UPDATE_TYPE.UNKNOWN;
  }

  const diff = semver.diff(installed, latest);
  if (diff === 'major') {
    return UPDATE_TYPE.MAJOR;
  }
  if (diff === 'minor') {
    return UPDATE_TYPE.MINOR;
  }
  if (diff === 'patch') {
    return UPDATE_TYPE.PATCH;
  }
  if (diff === 'prerelease') {
    return UPDATE_TYPE.PRERELEASE;
  }
  return UPDATE_TYPE.UNKNOWN;
}

function describeNonRegistryRow(wantedRange) {
  if (isNonRegistrySpec(wantedRange)) {
    return {
      skipRegistry: true,
      note: 'Non-registry spec (git/file/link/workspace)',
    };
  }
  return { skipRegistry: false, note: null };
}

module.exports = {
  classifyUpdateType,
  describeNonRegistryRow,
};

👉 Converts raw versions into actionable insights.

📄 `osvSecurity.js` (Security Engine)


/**
 * Map installed npm packages to security status using the OSV.dev API (Open Source Vulnerabilities).
 * @see https://google.github.io/osv.dev/api/
 */

const fs = require('fs');
const path = require('path');

const OSV_DEFAULT_BASE = 'https://api.osv.dev';
const OSV_ECOSYSTEM = 'npm';
const BATCH_SIZE = 150;
const VULN_FETCH_CONCURRENCY = 12;
const REQUEST_TIMEOUT_MS =
  Number(process.env.DEPENDENCY_REPORT_OSV_TIMEOUT_MS) || 120000;

/** @typedef {'none' | 'info' | 'low' | 'moderate' | 'high' | 'critical' | 'unknown'} SecurityLevel */

/**
 * @param {SecurityLevel} a
 * @param {SecurityLevel} b
 * @returns {SecurityLevel}
 */
function maxSeverity(a, b) {
  const rank = { none: 0, info: 1, low: 2, moderate: 3, high: 4, critical: 5, unknown: 0 };
  const ra = rank[a] ?? 0;
  const rb = rank[b] ?? 0;
  return ra >= rb ? a : b;
}

/**
 * @param {string} v
 */
function shouldSkipVersion(v) {
  if (!v || typeof v !== 'string') {
    return true;
  }
  const t = v.trim();
  if (!t || t === 'null' || t === 'undefined') {
    return true;
  }
  return /^(file:|git\+|git:|github:|link:|workspace:|\*)/i.test(t) || /^https?:\/\//i.test(t);
}

/**
 * Derive package name from a package-lock `packages` path key (lockfile v2+).
 * @param {string} key
 */
function nameFromLockPackagesKey(key) {
  const k = key.replace(/\\/g, '/');
  const i = k.lastIndexOf('node_modules/');
  if (i === -1) {
    return null;
  }
  return k.slice(i + 'node_modules/'.length) || null;
}

/**
 * @param {string} projectRoot
 * @returns {{ name: string, version: string }[] | null}
 */
function readPackageLockPairs(projectRoot) {
  const lockPath = path.join(projectRoot, 'package-lock.json');
  if (!fs.existsSync(lockPath)) {
    return null;
  }
  let lock;
  try {
    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
  } catch {
    return null;
  }

  /** @type {{ name: string, version: string }[]} */
  const out = [];
  const seen = new Set();

  function add(name, version) {
    if (!name || shouldSkipVersion(version)) {
      return;
    }
    const k = `${name}@${version}`;
    if (seen.has(k)) {
      return;
    }
    seen.add(k);
    out.push({ name, version: version.trim() });
  }

  if (lock.packages && typeof lock.packages === 'object') {
    for (const [pkgPath, meta] of Object.entries(lock.packages)) {
      if (!meta || typeof meta !== 'object' || !meta.version) {
        continue;
      }
      const name = typeof meta.name === 'string' ? meta.name : nameFromLockPackagesKey(pkgPath);
      add(name, meta.version);
    }
  } else if (lock.dependencies && typeof lock.dependencies === 'object') {
    const walk = (deps) => {
      if (!deps || typeof deps !== 'object') {
        return;
      }
      for (const [name, node] of Object.entries(deps)) {
        if (node && typeof node === 'object' && typeof node.version === 'string') {
          add(name, node.version);
        }
        if (node && node.dependencies) {
          walk(node.dependencies);
        }
      }
    };
    walk(lock.dependencies);
  }

  return out.length ? out : null;
}

/**
 * @param {Array<{ name: string, installedVersion?: string | null }>} rows
 */
function pairsFromRows(rows) {
  const seen = new Set();
  /** @type {{ name: string, version: string }[]} */
  const out = [];
  for (const r of rows) {
    const v = r.installedVersion;
    if (!v || shouldSkipVersion(v)) {
      continue;
    }
    const k = `${r.name}@${v}`;
    if (seen.has(k)) {
      continue;
    }
    seen.add(k);
    out.push({ name: r.name, version: v.trim() });
  }
  return out;
}

/**
 * @param {object} vuln
 * @returns {SecurityLevel}
 */
function severityFromVulnRecord(vuln) {
  if (!vuln || typeof vuln !== 'object') {
    return 'moderate';
  }

  let best = 0;
  const rank = { info: 1, low: 2, moderate: 3, high: 4, critical: 5 };

  /** @param {string} raw */
  const bumpFromLabel = (raw) => {
    if (!raw || typeof raw !== 'string') {
      return;
    }
    const s = raw.trim().toLowerCase();
    let r = 0;
    if (s === 'critical') {
      r = 5;
    } else if (s === 'high') {
      r = 4;
    } else if (s === 'moderate' || s === 'medium') {
      r = 3;
    } else if (s === 'low') {
      r = 2;
    } else if (s === 'info' || s === 'informational') {
      r = 1;
    }
    if (r > best) {
      best = r;
    }
  };

  const dsTop = vuln.database_specific;
  if (dsTop && typeof dsTop === 'object' && dsTop.severity) {
    bumpFromLabel(String(dsTop.severity));
  }

  if (Array.isArray(vuln.severity)) {
    for (const entry of vuln.severity) {
      if (!entry || typeof entry !== 'object') {
        continue;
      }
      const scoreStr = entry.score;
      if (typeof scoreStr === 'string') {
        const n = parseFloat(scoreStr);
        if (!Number.isNaN(n)) {
          if (n >= 9.0) {
            best = Math.max(best, 5);
          } else if (n >= 7.0) {
            best = Math.max(best, 4);
          } else if (n >= 4.0) {
            best = Math.max(best, 3);
          } else if (n > 0) {
            best = Math.max(best, 2);
          }
        }
      }
    }
  }

  for (const aff of vuln.affected || []) {
    if (!aff || typeof aff !== 'object') {
      continue;
    }
    const ds = aff.database_specific;
    const es = aff.ecosystem_specific;
    if (ds && typeof ds === 'object' && ds.severity) {
      bumpFromLabel(String(ds.severity));
    }
    if (es && typeof es === 'object' && es.severity) {
      bumpFromLabel(String(es.severity));
    }
  }

  if (best === 5) {
    return 'critical';
  }
  if (best === 4) {
    return 'high';
  }
  if (best === 3) {
    return 'moderate';
  }
  if (best === 2) {
    return 'low';
  }
  if (best === 1) {
    return 'info';
  }
  return 'moderate';
}

/**
 * @param {string} baseUrl
 * @param {unknown} body
 */
async function osvPostJson(baseUrl, pathname, body) {
  const url = `${baseUrl.replace(/\/$/, '')}${pathname}`;
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), REQUEST_TIMEOUT_MS);
  try {
    const res = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: 'application/json',
        'User-Agent': 'dependency-report/1.0 (+https://osv.dev)',
      },
      body: JSON.stringify(body),
      signal: ac.signal,
    });
    clearTimeout(timer);
    if (!res.ok) {
      return null;
    }
    return await res.json();
  } catch {
    clearTimeout(timer);
    return null;
  }
}

/**
 * @param {string} baseUrl
 * @param {string} id
 */
async function osvGetVuln(baseUrl, id) {
  const url = `${baseUrl.replace(/\/$/, '')}/v1/vulns/${encodeURIComponent(id)}`;
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), Math.min(REQUEST_TIMEOUT_MS, 60000));
  try {
    const res = await fetch(url, {
      method: 'GET',
      headers: {
        Accept: 'application/json',
        'User-Agent': 'dependency-report/1.0 (+https://osv.dev)',
      },
      signal: ac.signal,
    });
    clearTimeout(timer);
    if (!res.ok) {
      return null;
    }
    return await res.json();
  } catch {
    clearTimeout(timer);
    return null;
  }
}

/**
 * @param {{ name: string, version: string }[]} queries
 * @param {string} baseUrl
 * @returns {Promise<{ ok: boolean, idLists: string[][] }>}
 */
async function runQueryBatches(queries, baseUrl) {
  /** @type {string[][]} */
  const allResults = [];

  for (let i = 0; i < queries.length; i += BATCH_SIZE) {
    const chunk = queries.slice(i, i + BATCH_SIZE);
    const payload = {
      queries: chunk.map((q) => ({
        package: { ecosystem: OSV_ECOSYSTEM, name: q.name },
        version: q.version,
      })),
    };
    const json = await osvPostJson(baseUrl, '/v1/querybatch', payload);
    if (!json || !Array.isArray(json.results) || json.results.length !== chunk.length) {
      return { ok: false, idLists: [] };
    }
    for (let j = 0; j < chunk.length; j++) {
      const r = json.results[j];
      const vulns = Array.isArray(r?.vulns) ? r.vulns : [];
      const ids = vulns.map((v) => (v && v.id ? String(v.id) : '')).filter(Boolean);
      allResults.push(ids);
    }
  }

  return { ok: true, idLists: allResults };
}

/**
 * @param {string[]} ids
 * @param {string} baseUrl
 * @returns {Promise<Map<string, object>>}
 */
async function fetchVulnDetails(ids, baseUrl) {
  const unique = [...new Set(ids)];
  const map = new Map();
  if (unique.length === 0) {
    return map;
  }

  let next = 0;
  async function worker() {
    while (true) {
      const j = next++;
      if (j >= unique.length) {
        break;
      }
      const id = unique[j];
      const detail = await osvGetVuln(baseUrl, id);
      if (detail) {
        map.set(id, detail);
      }
    }
  }

  const nWorkers = Math.min(VULN_FETCH_CONCURRENCY, unique.length);
  await Promise.all(Array.from({ length: nWorkers }, () => worker()));
  return map;
}

/**
 * @param {{ name: string, version: string }[]} queries
 * @param {string[][]} idLists
 * @param {Map<string, object>} details
 * @returns {Map<string, { level: SecurityLevel, count: number }>}
 */
function aggregateByPackageName(queries, idLists, details) {
  /** @type {Map<string, Set<string>>} */
  const idsByName = new Map();

  for (let i = 0; i < queries.length; i++) {
    const { name } = queries[i];
    const ids = idLists[i] || [];
    for (const id of ids) {
      if (!idsByName.has(name)) {
        idsByName.set(name, new Set());
      }
      idsByName.get(name).add(id);
    }
  }

  /** @type {Map<string, { level: SecurityLevel, count: number }>} */
  const out = new Map();

  for (const [name, idSet] of idsByName) {
    let level = /** @type {SecurityLevel} */ ('moderate');
    for (const id of idSet) {
      const vuln = details.get(id);
      const sev = vuln ? severityFromVulnRecord(vuln) : 'moderate';
      level = maxSeverity(level, sev);
    }
    out.set(name, { level, count: idSet.size });
  }

  return out;
}

/**
 * @param {string} projectRoot
 * @param {Array<{ name: string, installedVersion?: string | null }>} rows
 * @returns {Promise<Map<string, { level: SecurityLevel, count: number }> | null>}
 */
async function fetchOsvSeverityMap(projectRoot, rows) {
  const baseUrl = String(process.env.DEPENDENCY_REPORT_OSV_API || OSV_DEFAULT_BASE).trim() || OSV_DEFAULT_BASE;

  const fromLock = readPackageLockPairs(projectRoot);
  const queries = fromLock && fromLock.length ? fromLock : pairsFromRows(rows);

  if (!queries.length) {
    return null;
  }

  const { ok, idLists } = await runQueryBatches(queries, baseUrl);
  if (!ok || idLists.length !== queries.length) {
    return null;
  }

  const allIds = idLists.flat();
  const details = await fetchVulnDetails(allIds, baseUrl);

  return aggregateByPackageName(queries, idLists, details);
}

/**
 * @param {SecurityLevel} level
 * @param {number} count
 */
function securityTooltip(level, count) {
  if (level === 'unknown') {
    return 'Security check unavailable (OSV request failed or invalid response)';
  }
  if (level === 'none') {
    return 'No known issues in OSV for queried versions';
  }
  const sev =
    level === 'critical'
      ? 'Critical'
      : level === 'high'
        ? 'High'
        : level === 'moderate'
          ? 'Moderate'
          : level === 'low'
            ? 'Low'
            : 'Info';
  return `${count} OSV record(s) — highest severity: ${sev}`;
}

/**
 * @param {string} projectRoot
 * @param {Array<{ name: string, installedVersion?: string | null }>} rows
 */
async function attachSecurityFromOsv(projectRoot, rows) {
  const fromLock = readPackageLockPairs(projectRoot);
  const queries = fromLock && fromLock.length ? fromLock : pairsFromRows(rows);

  if (!queries.length) {
    const msg =
      'Security check skipped: add package-lock.json or install deps so versions are known for OSV';
    for (const row of rows) {
      row.securityLevel = 'unknown';
      row.securityCount = 0;
      row.securityTooltip = msg;
    }
    return;
  }

  let byPkg;
  try {
    byPkg = await fetchOsvSeverityMap(projectRoot, rows);
  } catch {
    byPkg = null;
  }

  if (byPkg == null) {
    for (const row of rows) {
      row.securityLevel = 'unknown';
      row.securityCount = 0;
      row.securityTooltip = securityTooltip('unknown', 0);
    }
    return;
  }

  for (const row of rows) {
    const hit = byPkg.get(row.name);
    if (hit) {
      row.securityLevel = hit.level;
      row.securityCount = hit.count;
    } else {
      row.securityLevel = 'none';
      row.securityCount = 0;
    }
    row.securityTooltip = securityTooltip(row.securityLevel, row.securityCount);
  }
}

module.exports = {
  attachSecurityFromOsv,
  fetchOsvSeverityMap,
  securityTooltip,
  readPackageLockPairs,
  pairsFromRows,
  severityFromVulnRecord,
};

👉 Uses OSV.dev to:

Detect vulnerabilities
Assign severity levels

📄 `reportConsole.js` (CLI Output)


/**
 * CLI table: dark terminal + white text; Installed / Latest / Update use centered
 * calm pill tags (light fills + darker text; ANSI bg only on the label).
 */

// Enable ANSI colors when supported (some IDEs need this before chalk loads).
if (!process.env.NO_COLOR) {
  process.env.FORCE_COLOR = process.env.FORCE_COLOR || '3';
}

const chalk = require('chalk');
const Table = require('cli-table3');
const {
  UPDATE_TYPE,
  formatUpdateColumnLabel,
  PDF_TABLE,
  hexToRgb,
} = require('./constants');
const {
  summarizeDependencyRows,
  buildStructuredSummary,
  capitalizeSeverity,
} = require('./reportSummary');

/** Default body cells: bright white on terminal background. */
function cellPlain(text) {
  return chalk.white(String(text));
}

/** Table header: bold white (borders stay visible on dark terminals). */
function cellHeader(text) {
  return chalk.white.bold(String(text));
}

/**
 * @param {{ bg: string, fg: string }} style
 * @param {string} text
 */
function cellPill(style, text) {
  const [r, g, b] = hexToRgb(style.bg);
  const pad = ' ';
  return chalk.bgRgb(r, g, b).hex(style.fg).bold(`${pad}${text}${pad}`);
}

/** @param {string | null | undefined} version */
function cellInstalledVersion(version) {
  const t = version ?? '—';
  if (t === '—') {
    return chalk.gray('—');
  }
  return cellPill(PDF_TABLE.installedPill, t);
}

/** @param {string | null | undefined} version */
function cellLatestVersion(version) {
  const t = version ?? '—';
  if (t === '—') {
    return chalk.gray('—');
  }
  return cellPill(PDF_TABLE.latestPill, t);
}

/**
 * @param {string} updateType
 * @param {boolean} registryNote
 */
function cellUpdateType(updateType, registryNote) {
  const label = formatUpdateColumnLabel(updateType, registryNote);
  const style =
    PDF_TABLE.updateBadge[updateType] ?? PDF_TABLE.updateBadge[UPDATE_TYPE.UNKNOWN];
  return cellPill(style, label);
}

/**
 * Terminal Secure column: compact “icon” tile (saturated bg + light glyph) so it reads
 * clearly on dark backgrounds — same idea as a green check badge in GUI tools.
 * @param {string} bgHex
 * @param {string} fgHex
 * @param {string} symbol single character or short mark
 */
function cellSecureIcon(bgHex, fgHex, symbol) {
  const [r, g, b] = hexToRgb(bgHex);
  const pad = '  ';
  return chalk.bgRgb(r, g, b).hex(fgHex).bold(`${pad}${symbol}${pad}`);
}

/** bg / fg / symbol for each OSV outcome (✓ = no known vulns, ⚠ = vulnerability, — = check unavailable). */
const GLYPH_SECURE = '\u2713';
const GLYPH_UNSECURE = '\u26A0';

const SECURE_ICON = {
  none: { bg: '#2E7D50', fg: '#FFFFFF', symbol: GLYPH_SECURE },
  unknown: { bg: '#546E7A', fg: '#ECEFF1', symbol: '\u2014' },
  info: { bg: '#0277BD', fg: '#FFFFFF', symbol: 'i' },
  low: { bg: '#B45309', fg: '#FFFFFF', symbol: GLYPH_UNSECURE },
  moderate: { bg: '#EA580C', fg: '#FFFFFF', symbol: GLYPH_UNSECURE },
  high: { bg: '#DC2626', fg: '#FFFFFF', symbol: GLYPH_UNSECURE },
  critical: { bg: '#991B1B', fg: '#FFFFFF', symbol: GLYPH_UNSECURE },
};

/**
 * @param {{
 *   securityLevel?: string,
 *   securityCount?: number,
 *   securityTooltip?: string
 * }} r
 */
const SECURE_ICON_BY_LEVEL = {
  none: SECURE_ICON.none,
  unknown: SECURE_ICON.unknown,
  info: SECURE_ICON.info,
  low: SECURE_ICON.low,
  moderate: SECURE_ICON.moderate,
  high: SECURE_ICON.high,
  critical: SECURE_ICON.critical,
};

function cellSecure(r) {
  const level = r.securityLevel ?? 'unknown';
  const pick = SECURE_ICON_BY_LEVEL[level] ?? { bg: '#546E7A', fg: '#FFFFFF', symbol: '?' };
  return cellSecureIcon(pick.bg, pick.fg, pick.symbol);
}

/**
 * @param {number | null | undefined} n
 */
function formatBytes(n) {
  if (n == null || Number.isNaN(n)) {
    return '—';
  }
  if (n < 1024) {
    return `${n} B`;
  }
  if (n < 1024 * 1024) {
    return `${(n / 1024).toFixed(1)} KB`;
  }
  return `${(n / (1024 * 1024)).toFixed(2)} MB`;
}

/**
 * Registry publish time → relative phrasing (e.g. "18 days ago", "1 month ago").
 * @param {string | null | undefined} isoOrDateString
 */
function formatLastUpdate(isoOrDateString) {
  if (isoOrDateString == null || isoOrDateString === '') {
    return '—';
  }
  const then = new Date(isoOrDateString).getTime();
  if (Number.isNaN(then)) {
    return '—';
  }
  const now = Date.now();
  const diffSec = Math.floor((now - then) / 1000);
  if (diffSec < 0) {
    return new Date(isoOrDateString).toISOString().slice(0, 10);
  }
  if (diffSec < 60) {
    return 'just now';
  }
  const mins = Math.floor(diffSec / 60);
  if (mins < 60) {
    return mins === 1 ? '1 minute ago' : `${mins} minutes ago`;
  }
  const hours = Math.floor(mins / 60);
  if (hours < 24) {
    return hours === 1 ? '1 hour ago' : `${hours} hours ago`;
  }
  const days = Math.floor(hours / 24);
  if (days < 30) {
    if (days === 0) {
      return 'today';
    }
    if (days === 1) {
      return '1 day ago';
    }
    return `${days} days ago`;
  }
  const months = Math.floor(days / 30);
  if (months < 12) {
    if (months === 1) {
      return '1 month ago';
    }
    return `${months} months ago`;
  }
  const years = Math.floor(days / 365);
  if (years === 1) {
    return '1 year ago';
  }
  return `${years} years ago`;
}

/**
 * PDF “Generated:” line — local time, 12-hour clock.
 * @param {Date} [date]
 */
function formatGeneratedAt(date = new Date()) {
  return date.toLocaleString('en-US', {
    month: 'short',
    day: 'numeric',
    year: 'numeric',
    hour: 'numeric',
    minute: '2-digit',
    second: '2-digit',
    hour12: true,
    timeZoneName: 'short',
  });
}

/**
 * @param {Array<{
 *   name: string,
 *   kind: string,
 *   installedVersion: string | null,
 *   latestVersion: string | null,
 *   updateType: string,
 *   lastPublished: string | null,
 *   unpackedSizeBytes: number | null,
 *   registryError?: string | null,
 *   securityLevel?: string,
 *   securityCount?: number,
 *   securityTooltip?: string
 * }>} rows
 */
function printConsoleTable(rows) {
  const table = new Table({
    head: [
      cellHeader('Package'),
      cellHeader('Secure'),
      cellHeader('Installed'),
      cellHeader('Latest'),
      cellHeader('Update'),
      cellHeader('Size'),
      cellHeader('Last Update'),
    ],
    colAligns: ['left', 'center', 'center', 'center', 'center', 'right', 'left'],
    style: {
      head: [],
      border: ['gray'],
    },
    wordWrap: true,
  });

  for (const r of rows) {
    const lastUpdate = formatLastUpdate(r.lastPublished);
    const registryNote = Boolean(r.registryError);

    table.push([
      cellPlain(r.name),
      cellSecure(r),
      cellInstalledVersion(r.installedVersion),
      cellLatestVersion(r.latestVersion),
      cellUpdateType(r.updateType, registryNote),
      cellPlain(formatBytes(r.unpackedSizeBytes)),
      cellPlain(lastUpdate),
    ]);
  }

  console.log(`${table.toString()}\u001b[0m`);
  console.log(
    chalk.gray('Secure (OSV): ') +
      cellSecureIcon(SECURE_ICON.none.bg, SECURE_ICON.none.fg, SECURE_ICON.none.symbol) +
      chalk.gray(' secure · ') +
      cellSecureIcon(SECURE_ICON.moderate.bg, SECURE_ICON.moderate.fg, SECURE_ICON.moderate.symbol) +
      chalk.gray('/') +
      cellSecureIcon(SECURE_ICON.high.bg, SECURE_ICON.high.fg, SECURE_ICON.high.symbol) +
      chalk.gray(' vulnerabilities (by severity) · ') +
      cellSecureIcon(SECURE_ICON.unknown.bg, SECURE_ICON.unknown.fg, SECURE_ICON.unknown.symbol) +
      chalk.gray(' check unavailable'),
  );
}

const MAX_ADVISORY_CONSOLE = 15;

/** Slate horizontal rule (matches reference screenshots) */
const RULE = chalk.hex('#64748B');

/** List bullet for metric / action lines (single glyph + space) */
const LIST_BULLET = chalk.gray('\u2022');

/**
 * Terminal summary styled like the design reference: cyan section titles, aligned
 * key : value rows with colored numbers, vulnerabilities with arrow + severity emoji.
 * @param {Array<{
 *   name: string,
 *   updateType: string,
 *   securityLevel?: string,
 *   installedVersion?: string | null,
 * }>} rows
 */
function printConsoleSummary(rows) {
  const stats = summarizeDependencyRows(rows);
  const narrative = buildStructuredSummary(stats);
  const d = narrative.dashboard;
  const ind = '  ';
  const termW = process.stdout.columns || 80;
  const barW = Math.min(46, Math.max(36, termW - 4));

  /**
   * @param {string} title with optional leading emoji
   * @param {[string, string | number, (s: string) => string][]} rowsData label, raw value, chalk applier
   */
  function printMetricBlock(title, rowsData) {
    const labelW = Math.max(...rowsData.map(([a]) => a.length), [...title].length);
    const valW = Math.max(...rowsData.map(([, b]) => String(b).length), 1);
    const ruleLen = Math.min(barW, labelW + 3 + valW + 2);
    console.log('');
    console.log(`${ind}${chalk.cyan.bold(title)}`);
    console.log(`${ind}${chalk.gray('\u2500'.repeat(ruleLen))}`);
    for (const [label, val, valChalk] of rowsData) {
      const v = valChalk(String(val).padStart(valW));
      console.log(`${ind}${LIST_BULLET} ${chalk.gray(label.padEnd(labelW))} : ${v}`);
    }
  }

  console.log('');
  console.log(RULE('\u2501'.repeat(barW)));
  console.log(`${ind}${chalk.bold.white(`\uD83D\uDCE6 ${d.bannerTitle}`)}`);
  console.log(RULE('\u2501'.repeat(barW)));

  const o = d.overview;
  /** @type {[string, string | number, (s: string) => string][]} */
  const overviewRows = [
    ['Total Packages', o.totalPackages, (s) => chalk.white(s)],
    ['Up-to-date', o.upToDate, (s) => chalk.green(s)],
    ['Minor Updates', o.minorUpdates, (s) => chalk.yellow(s)],
    ['Patch Updates', o.patchUpdates, (s) => chalk.blue(s)],
    ['Major Updates', o.majorUpdates, (s) => chalk.red(s)],
    ['Unknown Status', o.unknownStatus, (s) => chalk.gray(s)],
  ];
  if (o.prerelease > 0) {
    overviewRows.push(['Prerelease semver', o.prerelease, (s) => chalk.magenta(s)]);
  }
  printMetricBlock('\uD83D\uDCCA Overview', overviewRows);

  const s = d.security;
  console.log('');
  console.log(`${ind}${chalk.cyan.bold('\uD83D\uDD10 Security')}`);
  if (s.osvIncomplete) {
    console.log(`${ind}${chalk.gray('\u2500'.repeat(Math.min(22, barW)))}`);
    console.log(
      `${ind}${chalk.yellow.bold('!')} ${chalk.white(
        `OSV did not complete \u2014 ${s.unverifiedPackages} package(s) unverified. Re-run with network and lockfile or install.`,
      )}`,
    );
  } else {
    const secLabels = ['Safe Packages', 'Vulnerable Packages'];
    if (s.unverifiedPackages > 0) {
      secLabels.push('Not assessed (OSV)');
    }
    if (s.severityBreakdown) {
      secLabels.push('By severity');
    }
    const secLabelW = Math.max(...secLabels.map((x) => x.length), 18);
    const numValW = Math.max(String(s.safePackages).length, String(s.vulnerablePackages).length, 1);
    const secRuleLen = Math.min(barW, Math.max(14, secLabelW + numValW + 8));
    console.log(`${ind}${chalk.gray('\u2500'.repeat(secRuleLen))}`);
    console.log(
      `${ind}${LIST_BULLET} ${chalk.gray('Safe Packages'.padEnd(secLabelW))} : ${chalk.green(String(s.safePackages).padStart(numValW))} ${chalk.green('\u2705')}`,
    );
    const vulnStr = String(s.vulnerablePackages);
    const vulnPad = vulnStr.padStart(numValW);
    const vulnLine =
      s.vulnerablePackages > 0
        ? chalk.red.bold(vulnPad) + chalk.red(' \uD83D\uDEA8')
        : chalk.green(`${vulnPad} \u2705`);
    console.log(`${ind}${LIST_BULLET} ${chalk.gray('Vulnerable Packages'.padEnd(secLabelW))} : ${vulnLine}`);
    if (s.unverifiedPackages > 0) {
      console.log(
        `${ind}${LIST_BULLET} ${chalk.gray('Not assessed (OSV)'.padEnd(secLabelW))} : ${chalk.hex('#EAB308')(String(s.unverifiedPackages))}`,
      );
    }
    if (s.severityBreakdown) {
      console.log(
        `${ind}${LIST_BULLET} ${chalk.gray('By severity'.padEnd(secLabelW))} : ${chalk.white(s.severityBreakdown)}`,
      );
    }
  }

  if (d.vulnerabilities.length > 0) {
    const vulnsShown = d.vulnerabilities.slice(0, MAX_ADVISORY_CONSOLE);
    const verStr = (v) => `@${v.version}`;
    const nameW = Math.min(
      28,
      Math.max(12, ...d.vulnerabilities.map((v) => v.name.length)),
    );
    const verW = Math.min(
      18,
      Math.max(10, ...d.vulnerabilities.map((v) => verStr(v).length)),
    );
    const lineW = Math.min(
      barW,
      2 + 1 + nameW + 2 + verW + 2 + 1 + 2 + 24,
    );
    console.log('');
    console.log(`${ind}${chalk.bold.hex('#F87171')('\uD83D\uDEA8 Vulnerabilities')}`);
    console.log(`${ind}${chalk.gray('\u2500'.repeat(Math.min(Math.max(18, lineW - 4), barW)))}`);
    for (const v of vulnsShown) {
      const sev = capitalizeSeverity(v.level);
      let name = v.name;
      if (name.length > nameW) {
        name = `${name.slice(0, Math.max(1, nameW - 1))}\u2026`;
      }
      name = name.padEnd(nameW);
      let ver = verStr(v);
      if (ver.length > verW) {
        ver = `${ver.slice(0, Math.max(1, verW - 1))}\u2026`;
      }
      ver = ver.padEnd(verW);
      const sevPart =
        v.level === 'critical' || v.level === 'high'
          ? chalk.red.bold(`${v.emoji} ${sev}`)
          : v.level === 'moderate'
            ? chalk.hex('#FB923C')(`${v.emoji} ${sev}`)
            : chalk.white(`${v.emoji} ${sev}`);
      console.log(
        `${ind}${LIST_BULLET} ${chalk.gray(name)}  ${chalk.gray(ver)}  ${chalk.gray('\u2192')}  ${sevPart}`,
      );
    }
    if (d.vulnerabilities.length > MAX_ADVISORY_CONSOLE) {
      console.log(
        `${ind}${chalk.gray(`\u2026 and ${d.vulnerabilities.length - MAX_ADVISORY_CONSOLE} more (OSV.dev)`)}`,
      );
    }
  }

  if (d.recommendationBullets.length > 0) {
    console.log('');
    console.log(`${ind}${chalk.cyan.bold('\uD83D\uDCA1 Recommendations')}`);
    console.log(`${ind}${chalk.gray('\u2500'.repeat(Math.min(18, barW)))}`);
    for (const b of d.recommendationBullets) {
      console.log(`${ind}${LIST_BULLET} ${chalk.gray(b.mark)} ${chalk.white(b.text)}`);
    }
  }

  const ruleShort = Math.min(31, barW);
  console.log('');
  console.log(`${ind}${RULE('\u2501'.repeat(ruleShort))}`);
  console.log(`${ind}${chalk.bold.hex('#FB7185')('\uD83D\uDEA8 PRIORITY ACTIONS')}`);
  console.log(`${ind}${RULE('\u2501'.repeat(ruleShort))}`);
  for (const p of d.priorityActions) {
    console.log(`${ind}${LIST_BULLET} ${chalk.bold.magenta(p.priority + ':')} ${chalk.white(p.text)}`);
  }

  console.log('');
  console.log(RULE('\u2501'.repeat(barW)));
  const tone = narrative.overallTone;
  const detailChalk =
    tone === 'success'
      ? chalk.green.bold
      : tone === 'danger'
        ? chalk.red.bold
        : tone === 'info'
          ? chalk.cyan.bold
          : chalk.hex('#FBBF24').bold;
  console.log(
    `${ind}${chalk.bold.white(`${narrative.overallLabel}:`)} ${detailChalk(`${narrative.overallEmoji} ${narrative.overallDetail}`)}`,
  );
  console.log(RULE('\u2501'.repeat(barW)));
  console.log('');
}

module.exports = {
  printConsoleTable,
  printConsoleSummary,
  formatBytes,
  formatLastUpdate,
  formatGeneratedAt,
};

👉 Produces:

Clean terminal table
Colored badges
Security indicators

📄 `reportPdf.js` (PDF Generator)


/**
 * PDF report (PDFKit): white rows; Installed / Latest / Update use centered pill tags.
 */

const fs = require('fs');
const PDFDocument = require('pdfkit');
const {
  PDF_TABLE,
  formatUpdateColumnLabel,
  UPDATE_TYPE,
  BADGE_LABEL_FG,
} = require('./constants');
const { formatBytes, formatLastUpdate, formatGeneratedAt } = require('./reportConsole');
const {
  summarizeDependencyRows,
  buildStructuredSummary,
  formatVulnerablePackageLine,
} = require('./reportSummary');

/**
 * Load a PNG/JPEG (or GIF) from an http(s) URL for the “secure” PDF icon.
 * Returns null on failure (caller falls back to the vector check).
 * @param {string} url
 * @param {{ timeoutMs?: number, maxBytes?: number }} [limits]
 * @returns {Promise<Buffer | null>}
 */
async function fetchSecureIconBuffer(url, limits = {}) {
  const timeoutMs =
    limits.timeoutMs ?? (Number(process.env.DEPENDENCY_REPORT_ICON_TIMEOUT_MS) || 8000);
  const maxBytes =
    limits.maxBytes ?? (Number(process.env.DEPENDENCY_REPORT_ICON_MAX_BYTES) || 524288);
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), timeoutMs);
  try {
    const res = await fetch(url, { signal: ac.signal, redirect: 'follow' });
    clearTimeout(timer);
    if (!res.ok) {
      return null;
    }
    const buf = Buffer.from(await res.arrayBuffer());
    if (!buf.length || buf.length > maxBytes) {
      return null;
    }
    return buf;
  } catch {
    clearTimeout(timer);
    return null;
  }
}

/**
 * Secure “clean” state: avoid Unicode ✓ in Helvetica (thin / missing). Use a vector check
 * in the PDF pill, or an embedded PNG when DEPENDENCY_REPORT_SECURE_ICON_URL loads.
 */
const GLYPH_INFO = 'i';
/** ASCII — always renders in Helvetica (avoid ⚠ for the same encoding issue). */
const GLYPH_ADVISORY = '!';

/**
 * @param {*} doc
 * @param {number} cx
 * @param {number} cy
 * @param {number} arm
 * @param {string} strokeColor
 */
function drawPdfCheckStroke(doc, cx, cy, arm, strokeColor) {
  doc.save();
  doc.strokeColor(strokeColor).lineWidth(1.05).lineCap('round').lineJoin('round');
  doc.moveTo(cx - arm * 0.78, cy + arm * 0.02);
  doc.lineTo(cx - arm * 0.1, cy + arm * 0.72);
  doc.lineTo(cx + arm * 0.98, cy - arm * 0.62);
  doc.stroke();
  doc.restore();
}

/**
 * Secure column pills reuse the same pastel + label colors as the Update column
 * (no custom shapes — matches Installed / Latest / Update visually).
 */
const SECURE_ISSUE_PILL = {
  info: PDF_TABLE.updateBadge[UPDATE_TYPE.PATCH],
  low: PDF_TABLE.updateBadge[UPDATE_TYPE.MINOR],
  moderate: { bg: '#FED7AA', fg: BADGE_LABEL_FG },
  high: PDF_TABLE.updateBadge[UPDATE_TYPE.MAJOR],
  critical: { bg: '#FECACA', fg: BADGE_LABEL_FG },
};

/**
 * @typedef {object} ReportRow
 * @property {string} name
 * @property {'dependencies'|'devDependencies'} kind
 * @property {string | null} installedVersion
 * @property {string | null} latestVersion
 * @property {string} updateType
 * @property {string | null} lastPublished
 * @property {number | null} unpackedSizeBytes
 * @property {string | null} [registryError]
 * @property {string} [securityLevel]
 * @property {number} [securityCount]
 * @property {string} [securityTooltip]
 */

/**
 * @param {string} updateType
 * @returns {{ bg: string, fg: string } | null}
 */
function updateBadgeColors(updateType) {
  return (
    PDF_TABLE.updateBadge[updateType] ??
    PDF_TABLE.updateBadge[UPDATE_TYPE.UNKNOWN]
  );
}

const TAG_FONT = 6.5;
const PILL_PAD_X = 7;
const PILL_PAD_Y = 3;
const PILL_RADIUS = 5;

/** Dark green for “all secure” summary line (matches Secure column tone). */
const SUMMARY_ALL_SECURE_FG = '#2D5A45';

/**
 * @param {string} outPath
 * @param {ReportRow[]} rows
 * @param {{ title?: string, secureIconUrl?: string }} [opts]
 */
async function writePdfReport(outPath, rows, opts = {}) {
  const iconUrl = String(opts.secureIconUrl || process.env.DEPENDENCY_REPORT_SECURE_ICON_URL || '').trim();
  let secureIconBuffer = null;
  if (iconUrl && /^https?:\/\//i.test(iconUrl)) {
    secureIconBuffer = await fetchSecureIconBuffer(iconUrl);
    if (!secureIconBuffer) {
      console.warn(
        'dependency-report: DEPENDENCY_REPORT_SECURE_ICON_URL could not be loaded; using built-in check icon in PDF.',
      );
    }
  }

  const title = opts.title || 'Bally Rewards React Native Dependency Report';
  const doc = new PDFDocument({
    size: 'A4',
    margin: 40,
    info: {
      Title: title,
      Author: 'Dependency Report Script',
    },
  });

  const stream = fs.createWriteStream(outPath);
  doc.pipe(stream);

  doc.fontSize(20).font('Helvetica-Bold').fillColor('#1a1a1a').text(title, { align: 'center' });
  doc.moveDown(0.3);
  doc
    .fontSize(10)
    .font('Helvetica')
    .fillColor('#333333')
    .text(`Generated: ${formatGeneratedAt()}`, { align: 'center' });
  doc.moveDown(1.2);

  const pageWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
  const x0 = doc.page.margins.left;
  /* Secure needs enough width so “Secure” stays on one line at 8pt (was wrapping as Secu/re). */
  /* Secure column: clean rows use a vector check (or custom PNG); vulnerable rows use ASCII “!”. */
  const weights = [1.88, 0.55, 0.92, 0.92, 0.88, 0.72, 1.13];
  const sum = weights.reduce((a, b) => a + b, 0);
  const cols = weights.map((w) => (w / sum) * pageWidth);
  const SECURE_COL = 1;
  const INSTALLED_COL = 2;
  const LATEST_COL = 3;
  const UPDATE_COL = 4;
  const SIZE_COL = 5;
  const LAST_UPDATE_COL = 6;

  const rowH = 22;
  const headerH = 26;
  let y = doc.y;

  function ensureSpace(heightNeeded) {
    if (y + heightNeeded > doc.page.height - doc.page.margins.bottom) {
      doc.addPage();
      y = doc.page.margins.top;
    }
  }

  function columnLeft(index) {
    let left = x0;
    for (let j = 0; j < index; j++) {
      left += cols[j];
    }
    return left;
  }

  /**
   * @param {number} x
   * @param {number} width
   * @param {string} text
   * @param {{ size?: number, bold?: boolean, color?: string, align?: 'left'|'center'|'right' }} [options]
   */
  function drawCellText(x, width, text, options = {}) {
    const t = String(text ?? '—');
    const align = options.align || 'left';
    doc.save();
    doc
      .font(options.bold ? 'Helvetica-Bold' : 'Helvetica')
      .fontSize(options.size || 7)
      .fillColor(options.color || PDF_TABLE.bodyText);
    doc.text(t, x + 4, y + 5, {
      width: width - 8,
      ellipsis: true,
      lineBreak: false,
      align,
    });
    doc.restore();
  }

  /**
   * Centered rounded pill (Installed, Latest, Update columns).
   * @param {number} ux
   * @param {number} colW
   * @param {string} label
   * @param {{ bg: string, fg: string }} style
   * @param {{ bold?: boolean, fontSize?: number }} [fontOpts]
   */
  function drawPill(ux, colW, label, style, fontOpts = {}) {
    const bold = fontOpts.bold !== false;
    const fs = typeof fontOpts.fontSize === 'number' ? fontOpts.fontSize : TAG_FONT;
    doc.save();
    const innerPad = 4;
    const maxTagW = Math.max(0, colW - innerPad * 2);

    doc.font(bold ? 'Helvetica-Bold' : 'Helvetica').fontSize(fs);
    const textW = doc.widthOfString(label);
    let tagW = Math.min(textW + PILL_PAD_X * 2, maxTagW);
    if (tagW < fs + PILL_PAD_X) {
      tagW = Math.min(maxTagW, fs + PILL_PAD_X * 2);
    }
    const tagH = fs + PILL_PAD_Y * 2;
    const tagX = ux + (colW - tagW) / 2;
    const tagY = y + (rowH - tagH) / 2;

    doc.roundedRect(tagX, tagY, tagW, tagH, PILL_RADIUS).fill(style.bg);
    doc.fillColor(style.fg);
    doc.font(bold ? 'Helvetica-Bold' : 'Helvetica').fontSize(fs);
    const lineH = doc.currentLineHeight(true);
    const textY = tagY + (tagH - lineH) / 2 + lineH * 0.08;
    doc.text(label, tagX, textY, {
      width: tagW,
      align: 'center',
      lineBreak: false,
      ellipsis: true,
    });
    doc.restore();
  }

  /**
   * Mint “secure” pill: optional remote PNG/JPEG in `iconBuffer`, else vector checkmark.
   * @param {number} ux
   * @param {number} colW
   * @param {Buffer | null} [iconBuffer]
   */
  function drawSecureCleanPill(ux, colW, iconBuffer) {
    const style = PDF_TABLE.latestPill;
    const fs = 7.2;
    const innerPad = 4;
    const maxTagW = Math.max(0, colW - innerPad * 2);
    let tagW = Math.min(fs + PILL_PAD_X * 2, maxTagW);
    const tagH = fs + PILL_PAD_Y * 2;
    const tagX = ux + (colW - tagW) / 2;
    const tagY = y + (rowH - tagH) / 2;
    doc.save();
    doc.roundedRect(tagX, tagY, tagW, tagH, PILL_RADIUS).fill(style.bg);
    const cx = tagX + tagW / 2;
    const cy = tagY + tagH / 2 + 0.35;
    const arm = Math.min(tagW, tagH) * 0.3;
    if (iconBuffer && Buffer.isBuffer(iconBuffer) && iconBuffer.length > 0) {
      try {
        const maxSide = Math.min(tagW - 2, tagH - 2, 11);
        const ix = tagX + (tagW - maxSide) / 2;
        const iy = tagY + (tagH - maxSide) / 2;
        doc.image(iconBuffer, ix, iy, { width: maxSide, height: maxSide, fit: [maxSide, maxSide] });
      } catch {
        drawPdfCheckStroke(doc, cx, cy, arm, style.fg);
      }
    } else {
      drawPdfCheckStroke(doc, cx, cy, arm, style.fg);
    }
    doc.restore();
  }

  // Header row
  ensureSpace(headerH);
  doc.save();
  doc.rect(x0, y, pageWidth, headerH).fill(PDF_TABLE.headerBg);
  doc.restore();

  let cx = x0;
  const headers = [
    'Package',
    'Secure',
    'Installed',
    'Latest',
    'Update',
    'Size',
    'Last Update',
  ];
  headers.forEach((h, i) => {
    doc.save();
    doc.font('Helvetica-Bold').fontSize(8).fillColor(PDF_TABLE.headerText);
    let hAlign = 'left';
    if (i === SECURE_COL || i === INSTALLED_COL || i === LATEST_COL || i === UPDATE_COL) {
      hAlign = 'center';
    }
    if (i === SIZE_COL) {
      hAlign = 'right';
    }
    doc.text(h, cx + 4, y + 8, {
      width: cols[i] - 8,
      align: hAlign,
      lineBreak: false,
      ellipsis: true,
    });
    doc.restore();
    cx += cols[i];
  });
  y += headerH;

  for (const r of rows) {
    ensureSpace(rowH);

    doc.save();
    doc.rect(x0, y, pageWidth, rowH).fill(PDF_TABLE.rowBg);
    doc.strokeColor(PDF_TABLE.grid).lineWidth(0.25);
    doc.rect(x0, y, pageWidth, rowH).stroke();
    doc.restore();

    const lastUpdate = formatLastUpdate(r.lastPublished);
    const registryNote = Boolean(r.registryError);
    const updateLabel = formatUpdateColumnLabel(r.updateType, registryNote);
    const badge = updateBadgeColors(r.updateType);

    drawCellText(columnLeft(0), cols[0], r.name, { align: 'left' });

    const secUx = columnLeft(SECURE_COL);
    const secW = cols[SECURE_COL];
    const secLevel = r.securityLevel ?? 'unknown';
    if (secLevel === 'none') {
      drawSecureCleanPill(secUx, secW, secureIconBuffer);
    } else if (secLevel === 'unknown') {
      drawCellText(secUx, secW, '\u2014', { align: 'center', size: 9, color: '#94A3B8' });
    } else if (secLevel === 'info') {
      drawPill(secUx, secW, GLYPH_INFO, SECURE_ISSUE_PILL.info, { fontSize: 7.2 });
    } else {
      const issueStyle = SECURE_ISSUE_PILL[secLevel] ?? SECURE_ISSUE_PILL.high;
      drawPill(secUx, secW, GLYPH_ADVISORY, issueStyle, { fontSize: 7.5 });
    }

    const installedText = r.installedVersion ?? '—';
    const latestText = r.latestVersion ?? '—';
    if (installedText === '—') {
      drawCellText(columnLeft(INSTALLED_COL), cols[INSTALLED_COL], '—', {
        align: 'center',
      });
    } else {
      drawPill(columnLeft(INSTALLED_COL), cols[INSTALLED_COL], installedText, PDF_TABLE.installedPill);
    }
    if (latestText === '—') {
      drawCellText(columnLeft(LATEST_COL), cols[LATEST_COL], '—', { align: 'center' });
    } else {
      drawPill(columnLeft(LATEST_COL), cols[LATEST_COL], latestText, PDF_TABLE.latestPill);
    }

    drawCellText(columnLeft(SIZE_COL), cols[SIZE_COL], formatBytes(r.unpackedSizeBytes), {
      align: 'right',
    });
    drawCellText(columnLeft(LAST_UPDATE_COL), cols[LAST_UPDATE_COL], lastUpdate, { align: 'left' });

    drawPill(columnLeft(UPDATE_COL), cols[UPDATE_COL], updateLabel, badge);

    y += rowH;
  }

  const stats = summarizeDependencyRows(rows);
  const narrative = buildStructuredSummary(stats);
  const summaryReserve =
    300 +
    Math.min(160, stats.withAdvisory.length * 12) +
    narrative.recommendationLines.length * 10;

  const needsRegistryFootnote = rows.some((row) => row.registryError);
  doc.moveDown(0.75);
  y = doc.y;
  /* Room for registry note + Summary (counts + secure list). */
  ensureSpace((needsRegistryFootnote ? 72 : 0) + summaryReserve);
  if (needsRegistryFootnote) {
    const footnoteRest =
      'If an update tag shows a trailing asterisk (*), the latest version could not be read from the npm registry. ' +
      'Typical reasons are git, file, link, or workspace dependencies, or a failed registry request.';
    doc
      .font('Helvetica-Bold')
      .fontSize(8)
      .fillColor('#555555')
      .text('Note: ', x0, y, { continued: true, lineBreak: false });
    doc
      .font('Helvetica')
      .fillColor('#666666')
      .text(footnoteRest, {
        width: pageWidth,
        lineGap: 2,
        align: 'left',
      });
    doc.moveDown(0.55);
    y = doc.y;
  }
  doc.moveDown(0.5);
  ensureSpace(Math.min(380, 260 + stats.withAdvisory.length * 11));

  const bulletX = x0 + 6;
  const bulletW = pageWidth - 12;

  doc.font('Helvetica-Bold').fontSize(10).fillColor('#1a1a1a').text('Summary', x0, doc.y, {
    width: pageWidth,
    lineGap: 2,
  });
  doc.moveDown(0.35);

  /**
   * @param {string} sectionTitle
   * @param {string[]} lines
   */
  function writeSummarySection(sectionTitle, lines) {
    doc.font('Helvetica-Bold').fontSize(8.5).fillColor('#1a1a1a').text(sectionTitle, x0, doc.y, {
      width: pageWidth,
      lineGap: 2,
    });
    doc.moveDown(0.14);
    doc.font('Helvetica').fontSize(8).fillColor('#374151');
    for (const line of lines) {
      doc.text(`• ${line}`, bulletX, doc.y, {
        width: bulletW,
        lineGap: 2.5,
        align: 'left',
      });
    }
    doc.moveDown(0.32);
  }

  writeSummarySection('Dependency Health Overview', narrative.healthLines);
  writeSummarySection('Security Status', narrative.securityLines);

  if (stats.withAdvisory.length > 0) {
    doc.font('Helvetica-Bold').fontSize(8).fillColor('#991B1B').text('Packages with vulnerabilities', x0, doc.y, {
      width: pageWidth,
      lineGap: 2,
    });
    doc.moveDown(0.1);
    doc.font('Helvetica').fontSize(8).fillColor('#444444');
    const maxList = 15;
    const list = stats.withAdvisory.slice(0, maxList);
    for (const entry of list) {
      doc.text(`• ${formatVulnerablePackageLine(entry)}`, bulletX + 2, doc.y, {
        width: bulletW - 2,
        lineGap: 1.5,
        align: 'left',
      });
    }
    if (stats.withAdvisory.length > maxList) {
      doc.text(
        `• ... and ${stats.withAdvisory.length - maxList} more (see OSV.dev)`,
        bulletX + 2,
        doc.y,
        { width: bulletW - 2, lineGap: 2 },
      );
    }
    doc.moveDown(0.28);
  }

  writeSummarySection('Recommendation', narrative.recommendationLines);

  const overallColor =
    narrative.overallTone === 'danger'
      ? '#B91C1C'
      : narrative.overallIsPositive
        ? SUMMARY_ALL_SECURE_FG
        : '#B45309';
  const yOverall = doc.y;
  const overallFs = 9;
  const overallGap = 4;
  doc.font('Helvetica-Bold').fontSize(overallFs);
  const overallLabelStr = `${narrative.overallLabel}: `;
  const labelW = doc.widthOfString(overallLabelStr);
  doc.fillColor('#1a1a1a').text(overallLabelStr, x0, yOverall, { lineBreak: false });

  const detailX = x0 + labelW + overallGap;
  doc.font('Helvetica-Bold').fontSize(overallFs).fillColor(overallColor);
  doc.text(narrative.overallDetail, detailX, yOverall, { lineBreak: false });

  doc.end();

  return new Promise((resolve, reject) => {
    stream.on('finish', () => resolve(outPath));
    stream.on('error', reject);
  });
}

module.exports = { writePdfReport };

👉 Generates:

Styled report
Visual badges
Summary insights

📄 `reportSummary.js` (Insight Engine)


/**
 * Shared dependency report summary (PDF + terminal): counts, narrative, recommendations.
 */

const { UPDATE_TYPE } = require('./constants');

/**
 * @param {Array<{
 *   name: string,
 *   updateType: string,
 *   securityLevel?: string,
 *   installedVersion?: string | null,
 * }>} rows
 */
function summarizeDependencyRows(rows) {
  const byUpdate = {
    minor: 0,
    major: 0,
    patch: 0,
    latest: 0,
    unknown: 0,
    prerelease: 0,
  };
  for (const r of rows) {
    switch (r.updateType) {
      case UPDATE_TYPE.MINOR:
        byUpdate.minor++;
        break;
      case UPDATE_TYPE.MAJOR:
        byUpdate.major++;
        break;
      case UPDATE_TYPE.PATCH:
        byUpdate.patch++;
        break;
      case UPDATE_TYPE.UP_TO_DATE:
        byUpdate.latest++;
        break;
      case UPDATE_TYPE.UNKNOWN:
        byUpdate.unknown++;
        break;
      case UPDATE_TYPE.PRERELEASE:
        byUpdate.prerelease++;
        break;
      default:
        byUpdate.unknown++;
    }
  }

  /** @type {{ name: string, level: string }[]} */
  const withAdvisory = [];
  let nClean = 0;
  let nAuditUnknown = 0;
  for (const r of rows) {
    const s = r.securityLevel ?? 'unknown';
    if (s === 'none') {
      nClean++;
    } else if (s === 'unknown') {
      nAuditUnknown++;
    } else if (s === 'info' || s === 'low' || s === 'moderate' || s === 'high' || s === 'critical') {
      const v = r.installedVersion;
      const installedVersion =
        v != null && String(v).trim() !== '' ? String(v).trim() : null;
      withAdvisory.push({ name: r.name, level: s, installedVersion });
    }
  }

  const allAuditClean = rows.length > 0 && nClean === rows.length && nAuditUnknown === 0;
  const allAuditUnknown = rows.length > 0 && nAuditUnknown === rows.length;

  return {
    total: rows.length,
    byUpdate,
    withAdvisory,
    nClean,
    nAuditUnknown,
    allAuditClean,
    allAuditUnknown,
  };
}

function capitalizeSeverity(level) {
  return level.charAt(0).toUpperCase() + level.slice(1);
}

/** Lower = more severe (OSV-style) */
const SEVERITY_ORDER = {
  critical: 0,
  high: 1,
  moderate: 2,
  low: 3,
  info: 4,
};

/**
 * @param {{ name: string, level: string, installedVersion: string | null }[]} list
 */
function sortAdvisoriesBySeverity(list) {
  return [...list].sort((a, b) => {
    const da = SEVERITY_ORDER[a.level] ?? 99;
    const db = SEVERITY_ORDER[b.level] ?? 99;
    if (da !== db) {
      return da - db;
    }
    return String(a.name).localeCompare(String(b.name));
  });
}

/**
 * @param {string} level
 */
function severityEmoji(level) {
  switch (level) {
    case 'critical':
      return '\uD83D\uDEA8';
    case 'high':
      return '\uD83D\uDD34';
    case 'moderate':
      return '\uD83D\uDFE0';
    case 'low':
      return '\uD83D\uDFE1';
    case 'info':
      return '\uD83D\uDD35';
    default:
      return '\u26A0\uFE0F';
  }
}

/**
 * @param {{ level: string }[]} withAdvisory
 */
function countSeverityBreakdown(withAdvisory) {
  const b = { critical: 0, high: 0, moderate: 0, low: 0, info: 0 };
  for (const e of withAdvisory) {
    if (b[e.level] !== undefined) {
      b[e.level]++;
    }
  }
  return b;
}

/**
 * @param {ReturnType<typeof countSeverityBreakdown>} b
 * @returns {string | null}
 */
function formatSeverityBreakdownLine(b) {
  const parts = [];
  const order = ['critical', 'high', 'moderate', 'low', 'info'];
  for (const k of order) {
    if (b[k] > 0) {
      parts.push(`${capitalizeSeverity(k)}: ${b[k]}`);
    }
  }
  return parts.length ? parts.join(' \u00B7 ') : null;
}

const MAX_INDIVIDUAL_ADVISORY_ACTIONS = 4;

/**
 * @param {*} stats
 * @returns {{ priority: string, text: string }[]}
 */
function buildPriorityActions(stats) {
  const { total, byUpdate, withAdvisory, allAuditUnknown } = stats;
  const { major, minor, patch, unknown } = byUpdate;
  const minorPatch = minor + patch;
  /** @type {{ priority: string, text: string }[]} */
  const out = [];

  if (total === 0) {
    return [{ priority: '\u2014', text: 'Add direct dependencies, then re-run this report' }];
  }

  function pushAction(text) {
    out.push({ priority: `P${out.length}`, text });
  }

  if (allAuditUnknown) {
    pushAction('Re-run when OSV checks complete (network, lockfile, installed deps)');
    if (major > 0) {
      pushAction(`Review ${major} major upgrade(s) for breaking changes`);
    }
    if (minorPatch > 0) {
      pushAction(`Apply ${minorPatch} minor/patch update(s) after OSV succeeds`);
    }
    return out;
  }

  const sorted = sortAdvisoriesBySeverity(withAdvisory);

  if (sorted.length > 0) {
    if (sorted.length <= MAX_INDIVIDUAL_ADVISORY_ACTIONS) {
      for (const e of sorted) {
        const sev = capitalizeSeverity(e.level);
        const urgent = e.level === 'critical' || e.level === 'high';
        pushAction(
          urgent
            ? `Fix ${e.name} immediately (${sev} \u2013 see OSV.dev)`
            : `Upgrade ${e.name} (${sev} advisory)`,
        );
      }
    } else {
      const top = sorted[0];
      pushAction(
        `Remediate ${sorted.length} packages with advisories (highest: ${capitalizeSeverity(top.level)} \u2013 start with ${top.name})`,
      );
    }
  }

  if (major > 0) {
    pushAction(`Review ${major} major update(s) for migration impact`);
  }
  if (minorPatch > 0) {
    pushAction(`Apply ${minorPatch} minor/patch update(s) in a maintenance window`);
  }
  if (unknown > 0) {
    pushAction(`Resolve ${unknown} package(s) with unknown semver/registry status`);
  }

  if (out.length === 0) {
    return [{ priority: '\u2014', text: 'No blocking actions; keep monitoring releases' }];
  }
  return out;
}

/**
 * One-line text for “Packages with vulnerabilities” (installed version OSV queried for this direct dep).
 * @param {{ name: string, level: string, installedVersion?: string | null }} entry
 */
function formatVulnerablePackageLine(entry) {
  const ver =
    entry.installedVersion && String(entry.installedVersion).trim() !== ''
      ? String(entry.installedVersion).trim()
      : 'unknown';
  return `${entry.name} @${ver} (highest: ${capitalizeSeverity(entry.level)})`;
}

/** @param {number} n @param {string} singular @param {string} plural */
function nounCount(n, singular, plural) {
  return `${n} ${n === 1 ? singular : plural}`;
}

/**
 * @param {{
 *   total: number,
 *   byUpdate: object,
 *   withAdvisory: { name: string, level: string, installedVersion: string | null }[],
 *   nClean: number,
 *   nAuditUnknown: number,
 *   allAuditClean: boolean,
 *   allAuditUnknown: boolean,
 * }} stats
 */
function buildStructuredSummary(stats) {
  const { total, byUpdate, withAdvisory, nClean, nAuditUnknown, allAuditClean, allAuditUnknown } = stats;
  const { minor, major, patch, latest, unknown, prerelease } = byUpdate;

  const healthLines = [
    `${total} package${total === 1 ? '' : 's'} analyzed`,
    `${minor} minor update${minor === 1 ? '' : 's'} available (safe to upgrade)`,
    `${major} major update${major === 1 ? '' : 's'} available (requires review)`,
    `${patch} patch update${patch === 1 ? '' : 's'} available (low-risk improvements)`,
    `${latest} package${latest === 1 ? '' : 's'} ${latest === 1 ? 'is' : 'are'} up to date`,
    `${unknown} package${unknown === 1 ? '' : 's'} ${unknown === 1 ? 'has' : 'have'} unknown status`,
  ];
  if (prerelease > 0) {
    healthLines.push(
      `${prerelease} package${prerelease === 1 ? '' : 's'} ${prerelease === 1 ? 'has' : 'have'} prerelease-related semver`,
    );
  }

  /** @type {string[]} */
  const securityLines = [];
  if (total === 0) {
    securityLines.push('No packages were included in this report.');
  } else if (withAdvisory.length > 0) {
    securityLines.push(
      `${nClean} package${nClean === 1 ? '' : 's'} ${nClean === 1 ? 'has' : 'have'} no known issues in OSV for queried versions`,
    );
    securityLines.push(
      `${withAdvisory.length} package${withAdvisory.length === 1 ? '' : 's'} ${withAdvisory.length === 1 ? 'has' : 'have'} known vulnerabilities (OSV.dev)`,
    );
    securityLines.push('Review the table and OSV records (https://osv.dev) for remediation steps.');
  } else if (allAuditClean) {
    securityLines.push(`All ${total} package${total === 1 ? '' : 's'} are secure`);
    securityLines.push('No vulnerabilities detected via OSV for queried versions');
    securityLines.push('No packages with known vulnerabilities');
  } else if (allAuditUnknown) {
    securityLines.push('OSV did not return usable results for this run');
    securityLines.push('Secure column shows - until OSV succeeds (network, lockfile, or API errors)');
    securityLines.push('Ensure package-lock.json exists or deps are installed, then re-run the report');
  } else {
    securityLines.push(
      `No known OSV vulnerabilities for ${nClean} package${nClean === 1 ? '' : 's'} where the check applied`,
    );
    securityLines.push(
      `${nAuditUnknown} package${nAuditUnknown === 1 ? '' : 's'} could not be assessed (OSV unavailable)`,
    );
  }

  /** @type {string[]} */
  const recommendationLines = [];
  if (total === 0) {
    recommendationLines.push('Add dependencies to package.json to populate this report.');
  } else {
    if (major > 0) {
      recommendationLines.push(
        `Prioritize upgrading ${nounCount(major, 'major dependency', 'major dependencies')} with caution`,
      );
    }
    if (minor > 0 || patch > 0) {
      const bits = [];
      if (minor > 0) {
        bits.push(`${minor} minor`);
      }
      if (patch > 0) {
        bits.push(`${patch} patch`);
      }
      recommendationLines.push(
        `Apply ${bits.join(' and ')} update${minor + patch === 1 ? '' : 's'} to keep the project current`,
      );
    }
    if (unknown > 0) {
      recommendationLines.push(`Investigate ${nounCount(unknown, 'package', 'packages')} with unknown status`);
    }
    if (withAdvisory.length > 0) {
      recommendationLines.push(
        `Remediate ${nounCount(withAdvisory.length, 'package', 'packages')} with known security vulnerabilities`,
      );
    }
    if (recommendationLines.length === 0) {
      recommendationLines.push('No semver upgrades flagged; continue monitoring for new releases.');
    }
  }

  let overallLabel = 'Overall Status';
  let overallDetail = '';
  let overallIsPositive = true;
  /** @type {'success'|'warning'|'danger'|'info'} */
  let overallTone = 'success';
  let overallEmoji = '\u2705';

  if (total === 0) {
    overallDetail = 'No data';
    overallIsPositive = false;
    overallTone = 'info';
    overallEmoji = '\u2139\uFE0F';
  } else if (withAdvisory.length > 0) {
    const worst = sortAdvisoriesBySeverity(withAdvisory)[0].level;
    overallIsPositive = false;
    if (worst === 'critical') {
      overallDetail = 'Needs attention \u2013 critical vulnerabilities present';
      overallTone = 'danger';
      overallEmoji = '\uD83D\uDEA8';
    } else if (worst === 'high') {
      overallDetail = 'Needs attention \u2013 high-severity vulnerabilities present';
      overallTone = 'danger';
      overallEmoji = '\uD83D\uDD34';
    } else if (worst === 'moderate') {
      overallDetail = 'Needs attention \u2013 moderate-severity advisories present';
      overallTone = 'warning';
      overallEmoji = '\uD83D\uDFE0';
    } else {
      overallDetail = 'Needs attention \u2013 security advisories present';
      overallTone = 'warning';
      overallEmoji = '\u26A0\uFE0F';
    }
  } else if (allAuditUnknown) {
    overallDetail = 'Security check incomplete \u2013 confirm OSV / lockfile and re-run';
    overallIsPositive = false;
    overallTone = 'warning';
    overallEmoji = '\u26A0\uFE0F';
  } else if (major > 0 || minor > 0 || patch > 0 || unknown > 0) {
    overallDetail = 'Healthy \u2013 pending semver upgrades';
    overallIsPositive = true;
    overallTone = 'warning';
    overallEmoji = '\u26A0\uFE0F';
  } else {
    overallDetail = 'Up to date \u2013 no upgrades flagged';
    overallIsPositive = true;
    overallTone = 'success';
    overallEmoji = '\u2705';
  }

  const sortedVulns = sortAdvisoriesBySeverity(withAdvisory);
  const vulnRows = sortedVulns.map((e) => ({
    name: e.name,
    version:
      e.installedVersion && String(e.installedVersion).trim() !== ''
        ? String(e.installedVersion).trim()
        : '\u2014',
    level: e.level,
    emoji: severityEmoji(e.level),
  }));

  const sevBreak = formatSeverityBreakdownLine(countSeverityBreakdown(withAdvisory));
  const recommendationBullets = [];
  if (minor > 0 || patch > 0) {
    recommendationBullets.push({ mark: '\u2714', text: 'Upgrade minor & patch dependencies regularly' });
  }
  if (major > 0) {
    recommendationBullets.push({ mark: '\u26A0', text: 'Review major updates for breaking changes' });
  }
  if (withAdvisory.length > 0) {
    recommendationBullets.push({ mark: '\u2757', text: 'Fix vulnerable packages per OSV guidance' });
  }
  if (unknown > 0) {
    recommendationBullets.push({ mark: '\u2753', text: 'Investigate unknown package resolution' });
  }
  if (recommendationBullets.length === 0 && total > 0) {
    recommendationBullets.push({ mark: '\u2714', text: 'Keep monitoring; re-run after dependency changes' });
  }

  const priorityActions = buildPriorityActions(stats);

  const dashboard = {
    bannerTitle: 'DEPENDENCY HEALTH REPORT',
    overview: {
      totalPackages: total,
      upToDate: latest,
      minorUpdates: minor,
      patchUpdates: patch,
      majorUpdates: major,
      unknownStatus: unknown,
      prerelease: byUpdate.prerelease ?? 0,
    },
    security: {
      safePackages: nClean,
      vulnerablePackages: withAdvisory.length,
      unverifiedPackages: nAuditUnknown,
      osvIncomplete: allAuditUnknown,
      severityBreakdown: sevBreak,
    },
    vulnerabilities: vulnRows,
    recommendationBullets,
    priorityActions,
    overall: {
      label: overallLabel,
      detail: overallDetail,
      isPositive: overallIsPositive,
      tone: overallTone,
      emoji: overallEmoji,
    },
  };

  return {
    healthLines,
    securityLines,
    recommendationLines,
    overallLabel,
    overallDetail,
    overallIsPositive,
    overallTone,
    overallEmoji,
    dashboard,
  };
}

module.exports = {
  summarizeDependencyRows,
  buildStructuredSummary,
  capitalizeSeverity,
  formatVulnerablePackageLine,
  severityEmoji,
  sortAdvisoriesBySeverity,
  buildPriorityActions,
};

👉 Converts data → decisions.

📄 `constants.js` (Shared Config)


/**
 * Shared constants for dependency reporting (colors, sort order, labels).
 */

/** @enum {string} */
exports.UPDATE_TYPE = {
  MAJOR: 'Major',
  MINOR: 'Minor',
  PATCH: 'Patch',
  UP_TO_DATE: 'Up to date',
  PRERELEASE: 'Prerelease',
  UNKNOWN: 'Unknown',
};

/** Sort priority: lower = earlier in list when sorting by update type. */
exports.UPDATE_TYPE_SORT_ORDER = {
  [exports.UPDATE_TYPE.MAJOR]: 0,
  [exports.UPDATE_TYPE.MINOR]: 1,
  [exports.UPDATE_TYPE.PATCH]: 2,
  [exports.UPDATE_TYPE.PRERELEASE]: 3,
  [exports.UPDATE_TYPE.UP_TO_DATE]: 4,
  [exports.UPDATE_TYPE.UNKNOWN]: 5,
};

/** Soft “light black” for badge text (calmer than #000, still readable on pastels). */
exports.BADGE_LABEL_FG = '#4B5563';

/**
 * PDF / shared pill colors (hex). Light, calm fills with darker text for contrast.
 */
exports.PDF_TABLE = {
  rowBg: '#FFFFFF',
  grid: '#DDE1E6',
  headerBg: '#2c3e50',
  headerText: '#FFFFFF',
  bodyText: '#1a1a1a',
  /** Version columns — dark text on light fills */
  installedPill: { bg: '#F3F4F6', fg: exports.BADGE_LABEL_FG },
  latestPill: { bg: '#D1FAE5', fg: exports.BADGE_LABEL_FG },
  /** Update status — soft pastels */
  updateBadge: {
    [exports.UPDATE_TYPE.MAJOR]: { bg: '#FEE2E2', fg: exports.BADGE_LABEL_FG },
    [exports.UPDATE_TYPE.MINOR]: { bg: '#FEF3C7', fg: exports.BADGE_LABEL_FG },
    [exports.UPDATE_TYPE.PATCH]: { bg: '#DBEAFE', fg: exports.BADGE_LABEL_FG },
    [exports.UPDATE_TYPE.UP_TO_DATE]: { bg: '#D1FAE5', fg: exports.BADGE_LABEL_FG },
    [exports.UPDATE_TYPE.UNKNOWN]: { bg: '#F3F4F6', fg: exports.BADGE_LABEL_FG },
    [exports.UPDATE_TYPE.PRERELEASE]: { bg: '#EDE9FE', fg: exports.BADGE_LABEL_FG },
  },
};

/** @param {string} hex #RRGGBB */
exports.hexToRgb = function hexToRgb(hex) {
  const h = hex.replace('#', '');
  return [
    parseInt(h.slice(0, 2), 16),
    parseInt(h.slice(2, 4), 16),
    parseInt(h.slice(4, 6), 16),
  ];
};

/**
 * @param {string} updateType
 * @param {boolean} registryNote
 */
exports.formatUpdateColumnLabel = function formatUpdateColumnLabel(updateType, registryNote) {
  const star = registryNote ? '*' : '';
  let label;
  if (updateType === exports.UPDATE_TYPE.UP_TO_DATE) {
    label = 'LATEST';
  } else if (updateType === exports.UPDATE_TYPE.UNKNOWN) {
    label = 'Unknown';
  } else {
    label = String(updateType).toUpperCase();
  }
  return `${label}${star}`;
};

👉 Central source of truth.

📄 `badges.js` (UI Styling Engine)


/**
 * npm / GitHub Primer–style badge system: flat chips, 1px border, tight padding,
 * monospace for semver (like registry UI), sans-semibold for status labels.
 */

const { UPDATE_TYPE, BADGE_LABEL_FG } = require('./constants');

/**
 * Layout tuned for PDF points (~11–12px equivalent at table scale).
 */
exports.NPM_BADGE_LAYOUT = {
  /** ~4px radius — flat chip, not a pill */
  radius: 3,
  borderWidth: 0.55,
  padX: 6.75,
  padY: 3.75,
  /** Courier = registry-style version strings */
  fontVersion: 7,
  fontStatus: 7.35,
};

/**
 * @typedef {{ bg: string, fg: string, border: string }} NpmBadgeStyle
 */

/** Installed / Latest — version column chips (Primer default + npm blue “latest”) */
exports.versionBadges = {
  installed: {
    bg: '#FFFFFF',
    fg: BADGE_LABEL_FG,
    border: '#D0D7DE',
  },
  latest: {
    bg: '#DDF4FF',
    fg: BADGE_LABEL_FG,
    border: '#79C0FF',
  },
};

/** Update column — Primer Label–style danger / attention / accent / success / neutral */
exports.statusBadges = {
  [UPDATE_TYPE.MAJOR]: {
    bg: '#FFEBE9',
    fg: BADGE_LABEL_FG,
    border: '#FF8182',
  },
  [UPDATE_TYPE.MINOR]: {
    bg: '#FFF8C5',
    fg: BADGE_LABEL_FG,
    border: '#EAC54F',
  },
  [UPDATE_TYPE.PATCH]: {
    bg: '#DDF4FF',
    fg: BADGE_LABEL_FG,
    border: '#79C0FF',
  },
  [UPDATE_TYPE.UP_TO_DATE]: {
    bg: '#DAFBE1',
    fg: BADGE_LABEL_FG,
    border: '#4AC26B',
  },
  [UPDATE_TYPE.UNKNOWN]: {
    bg: '#F6F8FA',
    fg: BADGE_LABEL_FG,
    border: '#D0D7DE',
  },
  [UPDATE_TYPE.PRERELEASE]: {
    bg: '#FBEFFF',
    fg: BADGE_LABEL_FG,
    border: '#D8B9FF',
  },
};

/**
 * @param {string} updateType
 * @returns {NpmBadgeStyle}
 */
exports.getStatusBadgeStyle = function getStatusBadgeStyle(updateType) {
  return exports.statusBadges[updateType] ?? exports.statusBadges[UPDATE_TYPE.UNKNOWN];
};

/**
 * @param {'version' | 'status'} kind
 */
function badgeFonts(kind) {
  if (kind === 'version') {
    return { family: 'Courier-Bold', size: exports.NPM_BADGE_LAYOUT.fontVersion };
  }
  return { family: 'Helvetica-Bold', size: exports.NPM_BADGE_LAYOUT.fontStatus };
}

/**
 * Draw a bordered, filled rounded rect + centered label (npm chip).
 * @param {object} doc PDFKit document
 * @param {number} ux column left
 * @param {number} colW column width
 * @param {number} rowTop
 * @param {number} rowH
 * @param {string} label
 * @param {NpmBadgeStyle} style
 * @param {'version' | 'status'} kind
 */
exports.drawNpmBadge = function drawNpmBadge(
  doc,
  ux,
  colW,
  rowTop,
  rowH,
  label,
  style,
  kind,
) {
  const L = exports.NPM_BADGE_LAYOUT;
  const innerPad = 2.5;
  const maxTagW = Math.max(0, colW - innerPad * 2);
  const { family, size } = badgeFonts(kind);

  doc.font(family).fontSize(size);
  const textW = doc.widthOfString(label);
  let tagW = Math.min(textW + L.padX * 2, maxTagW);
  const minW = size + L.padX * 1.25;
  if (tagW < minW) {
    tagW = Math.min(maxTagW, minW);
  }
  const tagH = size + L.padY * 2;
  const tagX = ux + (colW - tagW) / 2;
  const tagY = rowTop + (rowH - tagH) / 2;

  doc.save();
  doc.roundedRect(tagX, tagY, tagW, tagH, L.radius).fill(style.bg);
  doc
    .roundedRect(tagX, tagY, tagW, tagH, L.radius)
    .lineWidth(L.borderWidth)
    .strokeColor(style.border)
    .stroke();
  doc.fillColor(style.fg).font(family).fontSize(size);
  const lineH = doc.currentLineHeight(true);
  const textY = tagY + (tagH - lineH) / 2 + lineH * 0.065;
  doc.text(label, tagX, textY, {
    width: tagW,
    align: 'center',
    lineBreak: false,
    ellipsis: true,
  });
  doc.restore();
};

👉 Controls visual consistency across CLI & PDF.

📄 `package.json` (Script Entry)


"scripts": {
  "report:deps": "node src/config/scripts/dependency-report/generate-report.js"
}

👉 Run everything with:

yarn report:deps

⚠️ Honest Reality Check

npm registry calls can be slow
OSV dependency introduces risk
No CI/CD integration yet
Transitive deps not fully visible

🔗 References

🔥 Final Thought

Dependency management is no longer optional.

It’s a security layer.

If you're not tracking it properly — you're exposed.

React Native + Redux Toolkit: The Clean Way to Handle State

Amit Kumar — Sun, 07 Sep 2025 15:46:05 +0000

Managing state in React Native can get tricky as apps grow. Counters, inputs, API calls — they all add complexity.

That’s where Redux Toolkit (RTK) shines. It removes boilerplate, enforces best practices, and keeps your app state predictable.

In this post, we’ll build a React Native app with Redux Toolkit that covers three common use cases:

A counter state
An input field state
Fetching API data

🗂 Project Setup

Here’s the folder structure we’ll be working with:

src/
 ┣ screens/
 ┃ ┣ HomeScreen/
 ┃ ┃ ┗ index.js
 ┃ ┗ ProfileScreen/
 ┣ store/
 ┃ ┣ slice/
 ┃ ┃ ┣ apiSlice.js
 ┃ ┃ ┣ counterSlice.js
 ┃ ┃ ┣ InputSlice.js
 ┃ ┗ store.js
 ┗ vendor/

This structure clearly separates UI (screens) and state management (store). Each feature gets its own slice inside store/slice/, keeping logic modular and easy to maintain.

⚡ Configuring Redux Store

In store.js, we configure Redux Toolkit with three slices:

import { configureStore } from '@reduxjs/toolkit';
import counterReducer from './slice/counterSlice';
import inputReducer from './slice/InputSlice';
import apiReducer from './slice/apiSlice';

export const store = configureStore({
  reducer: {
    counter: counterReducer,
    input: inputReducer,
    api: apiReducer,
  },
});

Now, Redux knows how to handle counter, input, and API states independently.

Counter Slice

Let’s start with a simple counter.


import { createSlice } from '@reduxjs/toolkit';

const initialState = { counterValue: 0 };

export const counterSlice = createSlice({
  name: 'counter',
  initialState,
  reducers: {
    increment: state => { state.counterValue += 1; },
    decrement: state => { state.counterValue -= 1; },
    reset: state => { state.counterValue = 0; },
  },
});

export const { increment, decrement, reset } = counterSlice.actions;
export default counterSlice.reducer;

With just a few lines, we now have three actions: increment, decrement, and reset.

Input Slice

Now let’s handle user input:


import { createSlice } from '@reduxjs/toolkit';

const initialState = { inputValue: "Default Value" };

export const inputSlice = createSlice({
  name: 'input',
  initialState,
  reducers: {
    changeInputValue: (state, action) => {
      state.inputValue = action.payload;
    },
  },
});

export const { changeInputValue } = inputSlice.actions;
export default inputSlice.reducer;

Anytime the user types something, this slice updates the Redux store with the latest value.

API Slice

Finally, let’s fetch some data from an API.


import { createSlice } from '@reduxjs/toolkit';

const initialState = { macbook: null };

const apiSlice = createSlice({
  name: 'api',
  initialState,
  reducers: {
    setMacbook: (state, action) => {
      state.macbook = action.payload;
    },
  },
});

export const { setMacbook } = apiSlice.actions;

export const fetchMacbook = () => async dispatch => {
  const response = await fetch('https://api.restful-api.dev/objects/7');
  const data = await response.json();
  dispatch(setMacbook(data));
};

export default apiSlice.reducer;

When dispatched, this slice calls the API, retrieves MacBook details, and stores them in the Redux state.

Connecting Redux to React Native

In App.js, wrap the root component with Provider to make Redux available across the app:


import React from 'react';
import HomeScreen from './src/screens/HomeScreen';
import { Provider } from 'react-redux';
import { store } from './src/store/store';

const App = () => (
  <Provider store={store}>
    <HomeScreen />
  </Provider>
);

export default App;

🏡 HomeScreen Implementation

Here’s how the slices come together in the UI:

Counter Section → Increment, decrement, reset
Input Section → Save and display text
API Section → Fetch and render MacBook details

HomeScreen Code


import { StyleSheet, Text, TextInput, View, ScrollView, TouchableOpacity } from 'react-native';
import React, { useState } from 'react';
import { useDispatch, useSelector } from 'react-redux';
import { decrement, increment, reset } from '../../store/slice/counterSlice';
import { changeInputValue } from '../../store/slice/InputSlice';
import { fetchMacbook } from '../../store/slice/apiSlice';

const HomeScreen = () => {
  const [value, setValue] = useState('');
  const { counterValue } = useSelector(state => state.counter);
  const { inputValue } = useSelector(state => state.input);
  const { macbook } = useSelector(state => state.api);
  const dispatch = useDispatch();

  return (
    <ScrollView style={styles.scrollContainer}>
      <View style={styles.container}>
        <Text style={styles.appTitle}>🚀 Redux Toolkit Demo</Text>

        {/* Counter Section */}
        <View style={styles.smallCard}>
          <Text style={styles.smallCardTitle}>🔢 Counter: {counterValue}</Text>
          <View style={styles.buttonRow}>
            <TouchableOpacity style={[styles.smallButton, styles.incrementButton]} onPress={() => dispatch(increment())}>
              <Text style={styles.smallButtonText}>+</Text>
            </TouchableOpacity>
            <TouchableOpacity style={[styles.smallButton, styles.decrementButton]} onPress={() => dispatch(decrement())}>
              <Text style={styles.smallButtonText}>-</Text>
            </TouchableOpacity>
            <TouchableOpacity style={[styles.smallButton, styles.resetButton]} onPress={() => dispatch(reset())}>
              <Text style={styles.smallButtonText}>Reset</Text>
            </TouchableOpacity>
          </View>
        </View>

        {/* Input Section */}
        <View style={styles.smallCard}>
          <Text style={styles.smallCardTitle}>📝 Stored: {inputValue || 'None'}</Text>
          <View style={styles.inputRow}>
            <TextInput
              style={styles.compactInputStyle}
              value={value}
              onChangeText={setValue}
              placeholder="Enter text..."
              placeholderTextColor="#999"
            />
            <TouchableOpacity 
              style={[styles.smallButton, styles.saveButton]} 
              onPress={() => {
                dispatch(changeInputValue(value));
                setValue('');
              }}
            >
              <Text style={styles.smallButtonText}>Save</Text>
            </TouchableOpacity>
          </View>
        </View>

        {/* API Section */}
        <View style={styles.card}>
          <Text style={styles.cardTitle}>🌐 API Fetch</Text>
          <TouchableOpacity 
            style={[styles.button, styles.apiButton]} 
            onPress={() => dispatch(fetchMacbook())}
          >
            <Text style={styles.buttonText}>📡 Fetch MacBook Data</Text>
          </TouchableOpacity>

          {macbook && (
            <View style={styles.macbookContainer}>
              <Text style={styles.macbookTitle}>💻 {macbook.name}</Text>
              <View style={styles.specRow}>
                <Text style={styles.specLabel}>📅 Year:</Text>
                <Text style={styles.specValue}>{macbook.data.year}</Text>
              </View>
              <View style={styles.specRow}>
                <Text style={styles.specLabel}>💰 Price:</Text>
                <Text style={styles.specValue}>${macbook.data.price}</Text>
              </View>
              <View style={styles.specRow}>
                <Text style={styles.specLabel}>⚡ CPU:</Text>
                <Text style={styles.specValue}>{macbook.data['CPU model']}</Text>
              </View>
              <View style={styles.specRow}>
                <Text style={styles.specLabel}>💾 Storage:</Text>
                <Text style={styles.specValue}>{macbook.data['Hard disk size']}</Text>
              </View>
            </View>
          )}
        </View>
      </View>
    </ScrollView>
  );
};

export default HomeScreen;

const styles = StyleSheet.create({
  scrollContainer: {
    flex: 1,
    backgroundColor: '#f8f9fa',
  },
  container: {
    flex: 1,
    padding: 20,
    paddingTop: 60,
  },
  appTitle: {
    fontSize: 32,
    fontWeight: 'bold',
    textAlign: 'center',
    marginBottom: 30,
    color: '#2c3e50',
    textShadowColor: 'rgba(0,0,0,0.1)',
    textShadowOffset: { width: 1, height: 1 },
    textShadowRadius: 2,
  },
  card: {
    backgroundColor: 'white',
    borderRadius: 16,
    padding: 20,
    marginBottom: 20,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 4 },
    shadowOpacity: 0.1,
    shadowRadius: 8,
    elevation: 5,
  },
  smallCard: {
    backgroundColor: 'white',
    borderRadius: 12,
    padding: 15,
    marginBottom: 15,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.08,
    shadowRadius: 4,
    elevation: 3,
  },
  cardTitle: {
    fontSize: 20,
    fontWeight: '700',
    marginBottom: 15,
    color: '#34495e',
    textAlign: 'center',
  },
  smallCardTitle: {
    fontSize: 16,
    fontWeight: '600',
    marginBottom: 10,
    color: '#34495e',
  },
  counterDisplay: {
    alignItems: 'center',
    marginBottom: 20,
    backgroundColor: '#ecf0f1',
    borderRadius: 50,
    width: 100,
    height: 100,
    justifyContent: 'center',
    alignSelf: 'center',
  },
  counterValue: {
    fontSize: 36,
    fontWeight: 'bold',
    color: '#2c3e50',
  },
  buttonRow: {
    flexDirection: 'row',
    justifyContent: 'space-around',
    marginTop: 10,
  },
  button: {
    paddingVertical: 12,
    paddingHorizontal: 20,
    borderRadius: 25,
    alignItems: 'center',
    justifyContent: 'center',
    minWidth: 80,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.2,
    shadowRadius: 4,
    elevation: 3,
  },
  incrementButton: {
    backgroundColor: '#27ae60',
  },
  decrementButton: {
    backgroundColor: '#e74c3c',
  },
  resetButton: {
    backgroundColor: '#f39c12',
  },
  saveButton: {
    backgroundColor: '#3498db',
    marginTop: 15,
  },
  apiButton: {
    backgroundColor: '#9b59b6',
  },
  buttonText: {
    color: 'white',
    fontWeight: '600',
    fontSize: 16,
  },
  smallButton: {
    paddingVertical: 8,
    paddingHorizontal: 15,
    borderRadius: 20,
    alignItems: 'center',
    justifyContent: 'center',
    minWidth: 60,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 1 },
    shadowOpacity: 0.15,
    shadowRadius: 2,
    elevation: 2,
  },
  smallButtonText: {
    color: 'white',
    fontWeight: '600',
    fontSize: 14,
  },
  inputRow: {
    flexDirection: 'row',
    alignItems: 'center',
    gap: 10,
  },
  compactInputStyle: {
    flex: 1,
    borderWidth: 1,
    borderColor: '#bdc3c7',
    borderRadius: 8,
    padding: 10,
    fontSize: 14,
    backgroundColor: '#fff',
  },
  storedValueContainer: {
    backgroundColor: '#ecf0f1',
    padding: 15,
    borderRadius: 10,
    marginBottom: 15,
  },
  label: {
    fontSize: 14,
    color: '#7f8c8d',
    marginBottom: 5,
  },
  storedValue: {
    fontSize: 16,
    fontWeight: '600',
    color: '#2c3e50',
  },
  inputStyle: {
    borderWidth: 2,
    borderColor: '#bdc3c7',
    borderRadius: 12,
    padding: 15,
    fontSize: 16,
    backgroundColor: '#fff',
    marginBottom: 5,
  },
  macbookContainer: {
    backgroundColor: '#f8f9fa',
    borderRadius: 12,
    padding: 20,
    marginTop: 20,
    borderLeftWidth: 5,
    borderLeftColor: '#3498db',
  },
  macbookTitle: {
    fontSize: 18,
    fontWeight: 'bold',
    color: '#2c3e50',
    marginBottom: 15,
    textAlign: 'center',
  },
  specRow: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    alignItems: 'center',
    paddingVertical: 8,
    borderBottomWidth: 1,
    borderBottomColor: '#ecf0f1',
  },
  specLabel: {
    fontSize: 16,
    color: '#7f8c8d',
    fontWeight: '500',
  },
  specValue: {
    fontSize: 16,
    color: '#2c3e50',
    fontWeight: '600',
  },
});

👉 The UI reacts automatically when the Redux state updates.

🎯 Final Output

Tap +/- buttons → Counter updates
Enter text → Stored in Redux
Press Fetch button → MacBook data appears with name, year, price, CPU, and storage

✅ Why Redux Toolkit?

Less boilerplate than traditional Redux
Built-in Immer for immutability
Cleaner async thunks for API calls
Scalable for large apps

🚀 Conclusion

Redux Toolkit makes state management in React Native easier, cleaner, and scalable.
With just a few slices, we built a counter, input manager, and API fetcher — all in a structured, maintainable way.

If you’re starting a new project or refactoring an old one, Redux Toolkit is the way to go!

Handling Deep Links, Deferred Deep Links & User Invites/Referral Deeplink in React Native using AppsFlyer

Amit Kumar — Fri, 11 Jul 2025 17:35:51 +0000

Welcome to the ultimate guide for setting up deep links, deferred deep links, and user invites in your React Native app using AppsFlyer. Buckle up! This blog will walk you through everything—from SDK setup to sending users on magical journeys inside your app with a single click (or tap—we don't discriminate here).

📦 Step 1: Install the AppsFlyer SDK

Like every React Native adventure, we start in the terminal.

yarn add react-native-appsflyer

Step 2: Login to AppsFlyer Dashboard

Before anything, make sure you're logged into your AppsFlyer account. Don’t remember your password? Welcome to the club. Reset it and move on

👉 AppsFlyer Dashboard Login

Step 3: SDK Initialization

In your App.js or main screen (e.g., Home.js), call the initialization:

useEffect(() => {
    setupDeepLinkListeners();
    initAppflyerSDK();
}, []);

And define the initAppflyerSDK function like this:


import appsFlyer from 'react-native-appsflyer';
import { Platform } from 'react-native';

export const initAppflyerSDK = () => {
  try {
    appsFlyer.initSdk(
      {
        devKey: 'K2***********99', // Replace with your dev key
        isDebug: false,
        appId: '41*****44',       // iOS only
        onInstallConversionDataListener: true,
        onDeepLinkListener: true,
        timeToWaitForATTUserAuthorization: 10,
      },
      (result) => {
        console.log('🚀 AppsFlyer SDK initialized successfully:', result);

      },
      (error) => {
        console.error('❌ Error initializing AppsFlyer SDK:', error);
      }
    );
  } catch (error) {
    console.error('❌ Error initializing AppFlyer SDK:', error);
  }
};

Handle Deep Links (Direct & Deferred)

Now we plug in the listeners:


export const setupDeepLinkListeners = () => {
  try {
    // Direct Deep Link
    appsFlyer.onDeepLink((res) => {
      console.log('📩 Direct Deep Link received:', res);
      // Navigate your user here!
    });

    // Deferred Deep Link (First Install)
    appsFlyer.onInstallConversionData((res) => {
      console.log('🕰 Deferred Deep Link:', res);
      // Handle navigation based on your use case
    });
  } catch (error) {
    console.error('❌ Error setting up deep link listeners:', error);
  }
};

Custom Domains

If you're fancy and have custom domains, add this:

appsFlyer.setOneLinkCustomDomains(
  ['YOUR_CUSTOM_DOMAIN1', 'YOUR_CUSTOM_DOMAIN2'], 
  (success) => {
    console.log("Custom domains set successfully!", success);
  }, 
  (error) => {
    console.error("Failed to set custom domains:", error);
  }
);

iOS Setup (Don’t Skip This or Cry Later)

Update your AppDelegate.m (Objective-C):


#import <RNAppsFlyer.h>

// For iOS 9+
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary *) options {
  [[AppsFlyerAttribution shared] handleOpenUrl:url options:options];
  return YES;
}

// For iOS 8 and below
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString*)sourceApplication annotation:(id)annotation {
  [[AppsFlyerAttribution shared] handleOpenUrl:url sourceApplication:sourceApplication annotation:annotation];
  return YES;
}

// Universal Links
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
  [[AppsFlyerAttribution shared] continueUserActivity:userActivity restorationHandler:restorationHandler];
  return YES;
}

Swift Config

For Swift projects, update your AppDelegate with the following methods:

import AppsFlyerLib



  // MARK: - AppsFlyer Deeplink Handling

  // Deep linking - Open URI-scheme for iOS 9 and above
  func application(
    _ application: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
  ) -> Bool {
    AppsFlyerAttribution.shared().handleOpen(url, options: options)
    return true
  }

  // Deep linking - Open URI-scheme for iOS 8 and below
  func application(
    _ application: UIApplication,
    open url: URL,
    sourceApplication: String?,
    annotation: Any
  ) -> Bool {
    AppsFlyerAttribution.shared().handleOpen(url, sourceApplication: sourceApplication, withAnnotation: annotation)
    return true
  }

  // Open Universal Links
  func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
  ) -> Bool {
    AppsFlyerAttribution.shared().continue(userActivity, restorationHandler: { (array: [Any]?) in
      restorationHandler(array as? [UIUserActivityRestoring])
    })
    return true
  }

Bridging Header (if using Swift)

Make sure your bridging header imports the AppsFlyer SDK:

//  Use this file to import your target's public headers that you would like to expose to Swift.
#import <RNAppsFlyer.h>

Also, add this in your Associated Domains:

applinks:yourdeeplink.com

Android Deeplink Setup

AppsFlyer SDK inspects activity intent object during onResume(). Because of that, for each activity that may be configured or launched with any non-standard launch mode please make sure to add the following code to MainActivity.java in android/app/src/main/java/com...:

...
import android.content.Intent;
...
public class MainActivity extends ReactActivity {
...
    @Override
    public void onNewIntent(Intent intent) {
         super.onNewIntent(intent);
         setIntent(intent);
    }
 }

App Links

Update your AndroidManifest.xml:


<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
        android:host="yourdeeplink.com"
        android:scheme="https" />
</intent-filter>

🧪 Testing:

Now let's start testing Because We All Make Mistakes 🧪

👉 If a Deeplink is not hosted (Android Only):

For dev testing, go to App Info → Open by default → Supported web addresses → Toggle ON

Creating Your First Referral Deep Link: The Fun Part 🎨

Let's create a referral link (because sharing is caring):

Open AppsFlyer dashboard
Go to Home → Engage → OneLink Management
Click "New Link" (it's like magic, but with more clicking)
Select "referral-to-app" option
Choose "User_invite" and click next
Fill in the required fields (this is where you get creative)
Under "Additional parameters", add your custom data:

Parameter name: empId
Parameter value: 123
Add another for promotion: "ee"

Click "Create Link" and voilà! You're now a deep link wizard 🧙‍♂️

Ensure that your referral link includes the query parameters af_xp=referral and pid=User_invite; otherwise, the deferred deep link will not be recognized.

If you're generating the link using the User_Invite option (Referral-app), the required parameters will be automatically appended to the deep link, so there's no need to add them manually.

🧪 How to Test Deferred Deep Link

Testing deferred deep links can be tricky. The key thing to remember:

👉 Attribution SDKs only capture install attribution on a fresh install after a link click.

Follow these steps to test properly:

🔹 Step 1: Prepare Your Device

1 Uninstall the app from your device.
2 Click your deep link (e.g., referral/invite link).
3 Don’t install the app from the App/Play Store when redirected.

🔹 Step 2: Register Your Test Device in AppsFlyer

Go to AppsFlyer Console → Settings → Test Devices.
Click + Add device.
Install the My Device ID app to get your unique device ID:

iOS: My Device ID (App Store)
Android: My Device ID (Google Play)

4 Fill in the form:

Name: Unique identifier (use only English letters).
OS: iOS or Android.
Device ID type: Select IDFA (iOS) or AID (Android).
Device ID: Paste the ID from the app.

5 Click Save.

⚠️ Your device appears immediately, but may take a few minutes to activate.

🔗 Ref: AppsFlyer Docs – Register a Test Device

🔹 Step 3: Run the App Manually

After clicking the link, go back to your IDE (Android Studio or Xcode).
Run the app manually from there (don’t install via store).

✅ Why This Works

This simulates a deferred deep link install by letting the attribution SDK capture data on first open after link click.

If you install via Play Store/App Store directly, attribution won’t work because debug/test builds aren’t tracked like real store installs.

✨ Done! You’ve now tested deferred deep linking in a dev-friendly way.

Tracking User Engagement

Want to track how many users clicked your link or installed the app because of it?

Go to AppsFlyer Dashboard
Click your App Icon
Navigate to Campaign → Click
Scroll to see click stats, conversions, and deep link data

You're now officially stalking—err, "analyzing"—your users 👀

Inside React Native’s New Bridge: Codegen, TurboModules, and the Future

Amit Kumar — Fri, 20 Jun 2025 18:59:03 +0000

React Native is getting faster and cleaner. With the New Architecture, you don’t need to write tons of bridging code anymore. Thanks to Codegen and TurboModules, we now have:

✅ Automatic native binding
✅ Type-safe communication
✅ Better performance

In this guide, we’ll break down the concepts and build a real-world example module—step-by-step for both Android and iOS—that demonstrates:

✅ Sending a message from JS → Native
✅ Getting a message from Native → JS (via Promise)
✅ Using callbacks to return values
✅ Emitting real-time events from Native → JS

Let’s dive in. 👇

📘 What’s Codegen?

Codegen is the code generation system that automatically creates native interface files from TypeScript specifications.

✅ What Codegen Does:

Reads TypeScript spec files (like specs/NativeMessageModule.ts)
Generates native interface files for both Android and iOS
Creates type-safe bindings between JavaScript and native code
Handles the boilerplate code automatically

⚙️ What’s TurboModules?

Turbo Modules is the runtime architecture that provides fast, type-safe communication between JavaScript and native code.

✅ What Turbo Modules Does:

Provides the runtime infrastructure for native-JS communication
Implements the TurboModule interface
Offers better performance than the legacy bridge
Enables synchronous calls and better memory management

Aspect	Old Bridge	New (TurboModules + Codegen)
Manual bridging	✅ Required	❌ Auto-generated via Codegen
Performance	🐢 Slower	🚀 Much faster
Type safety	❌ Risk of mismatch	✅ Enforced via TypeScript
Native ↔ JS	Async only	Async + Sync support

Why Both Are Needed

Without Codegen: You'd have to manually write all the interface files
Without Turbo Modules: You'd still use the slow legacy bridge system
With Both: You get automatic code generation + fast runtime performance

Think of it this way:

Codegen = The factory that builds the blueprint
Turbo Modules = The engine that makes everything run fast

⚙️ My Current Configuration

Here's the exact setup I used for testing these solutions:

{
  "dependencies": {
    "react": "19.0.0",
    "react-native": "0.79.3"
  }
}

📁 Project Structure Overview

Here's how to structure your project to support TurboModules:


yourapp/
├── android/
│   └── app/
│       └── src/
│           └── main/
│               └── java/
│                   └── com/
│                       └── sampleapp/
│                           ├── NativeMessageModule.java
│                           ├── NativeMessagePackage.java
│                           └── MainApplication.java
├── ios/
│   ├── NativeMessageModule.h
│   └── NativeMessageModule.mm
├── specs/
│   └── NativeMessageModule.ts
├── App.js
├── package.json
└── ...

✅ Step-by-Step Android Example

1. 📄 specs/NativeMessageModule.ts

This is your TypeScript interface spec — the source of truth for Codegen.

import {TurboModule} from 'react-native/Libraries/TurboModule/RCTExport';
import {TurboModuleRegistry} from 'react-native';
import { EventEmitter } from 'react-native/Libraries/Types/CodegenTypes';

export interface Spec extends TurboModule {
  sendMessage(message: string): void;
  getMessage(): Promise<string>;
  sendWithCallback(callback: (response: string) => void): void;

  addListener(eventName: string): void;
  removeListeners(count: number): void;
  startSendingEvents(): void;
}

export default TurboModuleRegistry.getEnforcing<Spec>('NativeMessageModule');

All Native Turbo Module spec files must have the prefix Native, otherwise Codegen will ignore them.

The string 'NativeMessageModule' must exactly match public static final String NAME = "NativeMessageModule"; in your Java module. This consistency is critical for Codegen and TurboModules to connect properly.

2. 🧠 codegenConfig in package.json

Tells Codegen how to generate files.

"codegenConfig": {
  "name": "NativeMessageModule",
  "type": "modules",
  "jsSrcsDir": "specs",
  "android": {
    "javaPackageName": "com.turbomodules" #Replace this with your packagename
  }
}

android

Codegen is executed through the generateCodegenArtifactsFromSchema Gradle task:


cd android
./gradlew generateCodegenArtifactsFromSchema

BUILD SUCCESSFUL in 837ms
14 actionable tasks: 3 executed, 11 up-to-date

This is automatically run when you build your Android application.

iOS

You need to install the pods to make sure that codegen runs to generate the new files:

cd ios 
pod install

3. 🧱 `NativeMessageModule.java`

✅ File: NativeMessageModule.java

📍 Path: android/app/src/main/java/com/sampleapp/NativeMessageModule.java

This is your real native logic class.


package com.turbomodules; #Replace this with your packagename

package com.turbomodules;

import android.os.Handler;
import android.os.Looper;

import com.facebook.react.bridge.Promise;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.Callback;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.module.annotations.ReactModule;
import com.facebook.react.modules.core.DeviceEventManagerModule;

@ReactModule(name = NativeMessageModule.NAME)
public class NativeMessageModule extends NativeMessageModuleSpec {
    public static final String NAME = "NativeMessageModule";

    public NativeMessageModule(ReactApplicationContext reactContext) {
        super(reactContext);
    }

    // 1. Send message (no return)
    public void sendMessage(String message) {
        System.out.println("Received from JS: " + message);
    }

    // 2. Return message using Promise
    public void getMessage(Promise promise) {
        try {
            String message = "Hello from Android";
            promise.resolve(message);
        } catch (Exception e) {
            promise.reject("GET_MESSAGE_ERROR", e);
        }
    }

    // 3. Return message using Callback
    public void sendWithCallback(Callback callback) {
        String response = "Callback response from Android";
        callback.invoke(response);
    }

    // 4. Send event to JS
    @Override
    public void addListener(String eventName) {
        // Required for Turbo Module event emitters
        // This is called automatically when JS adds a listener
    }

    // 5. Remove event listeners
    @Override
    public void removeListeners(double count) {
        // Required for Turbo Module event emitters
        // This is called automatically when JS removes listeners
    }

    // 6. Emit an event to JS
    @ReactMethod
    public void startSendingEvents() {
        Handler handler = new Handler(Looper.getMainLooper());
        for (int i = 1; i <= 5; i++) {
            int delay = i * 1000;
            handler.postDelayed(() -> {
                WritableMap map = Arguments.createMap();
                map.putString("message", "Event at " + System.currentTimeMillis());
                getReactApplicationContext()
                    .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
                    .emit("onTimerTick", map);
            }, delay);
        }
    }
}

4. 📦 NativeMessagePackage.java

✅ File: NativeMessagePackage.java
📍 Path:
android/app/src/main/java/com/sampleapp/NativeMessagePackage.java

Registers your module in the app.


package com.turbomodules; #Replace this with your packagename

import com.facebook.react.ReactPackage;
import com.facebook.react.bridge.*;
import com.facebook.react.uimanager.ViewManager;
import java.util.List;

public class NativeMessagePackage implements ReactPackage {
    @Override
    public List<NativeModule> createNativeModules(ReactApplicationContext context) {
        return List.of(new NativeMessageModule(context));
    }

    @Override
    public List<ViewManager> createViewManagers(ReactApplicationContext context) {
        return List.of();
    }
}

💡 Why needed: This is how you expose your native module to React Native.

5. 🏠 `MainApplication.java`

✅ File: MainApplication.java
📍 Path:
android/app/src/main/java/com/sampleapp/MainApplication.java


import com.turbomodules.NativeMessagePackage #Replace this with your packagename

add(NativeMessagePackage())

6. ✅ Step-by-Step iOS Example

With the Android module complete, let’s build the iOS side of our NativeMessageModule. We'll use Objective-C++ with TurboModules and Codegen to enable seamless native-JS communication.

📁 Step 1: Open the Xcode Workspace

Navigate to the ios folder and open your project workspace in Xcode:

cd ios
open TurboModuleExample.xcworkspace

📦 Step 2: Create a New Group

In Xcode:

Right-click your app folder (e.g., TurboModuleExample)
Select New Group
Name it: NativeMessageModule

✅ This keeps native modules organized by feature.

🧱 Step 3: Add a New Cocoa Touch Class

Now add the module class file:

Right-click NativeMessageModule group
Select New File from Templetes...

Step 4: Choose Cocoa Touch Class

⚙️ Step 5: Name the Cocoa Touch Class `NativeMessageModule` with the Objective-C language.

Note:- Rename NativeMessageModule.m → NativeMessageModule.mmmaking it an Objective-C++ file.

Final file Structure

Here's what your folder structure should look like:

✅ Configure the Bridging Header

To ensure proper bridging between Swift and Objective-C:

Go to Build Settings in your Xcode project.
Search for Objective-C Bridging Header.
Set the path relative to your project like this:

🧬 Step 6: Implement the Native Module

Update the content of both NativeMessageModule.h and NativeMessageModule.mm as follows:

📄 NativeMessageModule.h


//
//  NativeMessageModule.h
//  newArchitectureBridge
//
//  Created by Amit Kumar on 21/06/25.
//

#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

NS_ASSUME_NONNULL_BEGIN

@interface NativeMessageModule : RCTEventEmitter <RCTBridgeModule>

@end

NS_ASSUME_NONNULL_END

⚙️ NativeMessageModule.mm
Now update NativeMessageModule.mm

//
//  NativeMessageModule.mm
//  newArchitectureBridge
//
//  Created by Amit Kumar on 21/06/25.
//

#import "NativeMessageModule.h"

@implementation NativeMessageModule {
  BOOL hasListeners;
}

RCT_EXPORT_MODULE();

+ (BOOL)requiresMainQueueSetup {
  return YES;
}

- (NSArray<NSString *> *)supportedEvents {
  return @[@"onTimerTick"];
}

// Called when the first JS listener is added
- (void)startObserving {
  hasListeners = YES;
}

// Called when the last JS listener is removed
- (void)stopObserving {
  hasListeners = NO;
}

RCT_EXPORT_METHOD(sendMessage:(NSString *)message) {
  NSLog(@"[iOS] Received from JS: %@", message);
}

RCT_EXPORT_METHOD(getMessage:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject) {
  NSString *response = @"Hello from iOS";
  NSLog(@"[iOS] Returning to JS (Promise): %@", response);
  resolve(response);
}

RCT_EXPORT_METHOD(sendWithCallback:(RCTResponseSenderBlock)callback) {
  NSString *response = @"Hello from iOS";
  NSLog(@"[iOS] Returning to JS (Callback): %@", response);
  callback(@[response]);
}

RCT_EXPORT_METHOD(startSendingEvents) {
  if (!hasListeners) {
    NSLog(@"[iOS] No listeners, not sending events");
    return;
  }

  for (int i = 1; i <= 8; i++) {
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(i * NSEC_PER_SEC)),
                   dispatch_get_main_queue(), ^{
      if (!hasListeners) return;
      NSString *msg = [NSString stringWithFormat:@"Event at %f", [[NSDate date] timeIntervalSince1970]];
      [self sendEventWithName:@"onTimerTick" body:@{@"message": msg}];
    });
  }
}

@end

7. 🧪 JS Test: App.js

import React, {useState, useEffect} from 'react';
import {
  View,
  Button,
  Text,
  StyleSheet,
  NativeEventEmitter,
  NativeModules,
} from 'react-native';
import NativeMessageModule from './specs/NativeMessageModule';

const App = () => {
  const [receivedMessage, setReceivedMessage] = useState('');
  const [lastSentMessage, setLastSentMessage] = useState('');
  const [callbackMsg, setCallbackMsg] = useState('');
  const [eventMsg, setEventMsg] = useState('');

  useEffect(() => {
    const eventEmitter = new NativeEventEmitter(
      NativeMessageModule,
    );
    const subscription = eventEmitter.addListener('onTimerTick', event => {
      console.log('Event received:', event.message);
      setEventMsg(event.message);
    });
    return () => subscription?.remove();
  }, []);

  const startListening = () => {
    NativeMessageModule.startSendingEvents();
  };

  const sendMessageToNative = () => {
    const message = 'Hello from React Native';
    NativeMessageModule.sendMessage(message);
    setLastSentMessage(message);
  };

  const getMessageFromNative = () => {
    try {
      const message = NativeMessageModule.getMessage();
      setReceivedMessage(message);
    } catch (error) {
      console.error(error);
    }
  };

  const useCallbackMessage = () => {
    NativeMessageModule.sendWithCallback(msg => {
      setCallbackMsg(msg);
    });
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Bridging Example</Text>

      <View style={styles.buttonContainer}>
        <Button title="Send Message to Native" onPress={sendMessageToNative} />
        <Text style={styles.message}>Last sent: {lastSentMessage}</Text>
      </View>

      <View style={styles.buttonContainer}>
        <Button
          title="Get Message from Native"
          onPress={getMessageFromNative}
        />
        <Text style={styles.message}>Received: {receivedMessage}</Text>
      </View>

      <View>
        <Button title="Use Callback" onPress={useCallbackMessage} />
        <Text>Received: {callbackMsg}</Text>
      </View>

      <View>
        <Button title="Trigger Native Event" onPress={startListening} />
        <Text>Received: {eventMsg}</Text>
      </View>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {flex: 1, justifyContent: 'center', padding: 16},
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 32,
    textAlign: 'center',
  },
  buttonContainer: {marginBottom: 24},
  message: {marginTop: 8, fontSize: 14, color: '#666'},
});

export default App;

Final Output

🎯 Conclusion

With TurboModules and Codegen, React Native’s new architecture simplifies bridging and boosts performance:

No more boilerplate for native interfaces
Faster & safer communication
Clear folder structure for maintainability

Whether you're migrating from the legacy bridge or starting fresh, this setup gives you everything you need to build efficient, modern native modules.

🚀 How to Upgrade Your React Native Project to the New Architecture (v0.79+)

Amit Kumar — Sat, 14 Jun 2025 07:42:41 +0000

With the evolution of React Native, the New Architecture brings significant performance and maintainability improvements through features like TurboModules, Fabric, and C++ shared logic. Upgrading to this architecture can seem intimidating—but with the right strategy, it's achievable.

In this blog, I’ll walk you through two practical approaches to upgrading your project to the New Architecture in React Native (v0.79.3 at the time of writing), the recommended approach, the challenges I faced, and how I overcame them.

In this guide, I’ll walk you through:

✅ Two practical upgrade approaches
🛠️ The recommended method
⚔️ Challenges I faced
💡 How I solved them
🛠️ Solutions to Each Problem
✅ Migration Checklist
🚫 Common Mistakes to Avoid
🎁 Final Checklist Before You Go Live

📌 When Should You Consider Upgrading?

If your current project is within 2 to 4 versions of the latest release, upgrading is relatively safe. Otherwise, it’s better to migrate code manually to a fresh project. We’ll cover both methods.

🚀 From 0.71.0 to 0.79.3: My New Architecture Journey

I upgraded from React Native 0.71 to 0.79 for New Architecture support

🛠️ Approach 1: Upgrade Using React Native Upgrade Helper (Recommended for Small Version Gaps)

This method is ideal if your current version is just a few versions behind (e.g., 0.75 to 0.79).

Step 1. Update Android Studio

Make sure you’re using the latest stable version of Android Studio.
This ensures compatibility with the updated Gradle, SDKs, and React Native tooling.

Step 2. Use the React Native Upgrade Helper

Visit React Native Upgrade Helper.
Select your current version (left) and target version (right, e.g., 0.79.3).

Step 3. Follow the Diff Instructions Carefully

Pay special attention to native file changes—these are critical for enabling the New Architecture.
Use version control to commit incrementally and rollback if needed.

📦 Update Third-Party Dependencies

Once you’re on the latest version, update your dependencies:

Visit React Native Directory
Apply the filter: "Supports New Architecture"
Replace or upgrade libraries accordingly

✅ Approach 2: Create a Fresh Project (Recommended for larger Version Gaps)

If your current project is outdated or complex, this is the safest and cleanest way to upgrade.

🧱 Steps to Migrate

Step 1. Create a New Project

npx @react-native-community/cli init  MyApp

Step 2. Migrate Your Existing Codebase

Once your new React Native project is created (preferably using the latest stable version like v0.79.3), it’s time to bring your existing app logic into the new environment.

📁 Step 3: Move Your src/ Folder

Start by copying the entire src directory from your old project into the root of the new project

📦 Step 4: Sync and Install Dependencies

Now, open both the old and new package.json files side by side.

Carefully review the dependencies and devDependencies.
Instead of copying everything directly, manually install each package in the new project using the latest version.
Ensure that each dependency you bring in is compatible with React Native's New Architecture.

Yes, it's manual—but it's also bulletproof for both Android and iOS

✅ Step 5: Verify It Works

After you've copied your source code and installed the updated dependencies:

Clean the Android build (optional but recommended):

cd android && ./gradlew clean && cd ..

Run the app on both platforms to ensure everything is wired correctly:

npx react-native run-android
npx react-native run-ios

Watch the terminal and device logs for any errors, warnings, or compatibility issues.

💡 Tip: If any dependency causes issues with the new architecture, check the package's documentation or GitHub issues. Some packages may still require legacy support or additional configuration to work correctly.

🧩 Challenges I Faced (And How I Solved Them)

As I migrated to the New React Native Architecture, I ran into some unexpected issues that weren’t immediately obvious. Here's a breakdown of the most common ones — and how I resolved each.

🔥Common Issues (React Native New Architecture)

💡 Note: I’ve included dedicated solution links at the end of this section for deeper dives.

🌐1. Translation failed

The old way of handling translations using i18n-js no longer works reliably in the new architecture.

✅ The recommended and stable alternative is react-i18next, which is modern, flexible, and actively maintained.

⚛️2. Redux not working

Redux can break in the new architecture, especially if you're using older packages like 'redux' and 'redux-thunk'.

The new approach uses the modern Redux Toolkit:

import { configureStore } from "@reduxjs/toolkit";

🔁 You don’t need to refactor your entire Redux logic.
Just update your store configuration. Actions, reducers, and selectors will continue to work as before.

Replace this


import {createStore, applyMiddleware, compose} from 'redux';
import thunk from 'redux-thunk';
import rootReducer from './rootReducer';
const composeStore = compose(applyMiddleware(thunk));
export const appStore = createStore(rootReducer, composeStore);
const store = () => {
  return appStore;
};

export default store;

With this


import {configureStore} from "@reduxjs/toolkit";
import rootReducer from "./rootReducer";

export const appStore = configureStore({
  reducer: rootReducer,
  devTools: true,
  middleware: getDefaultMiddleware => getDefaultMiddleware(),
});

const store = () => {
  return appStore;
};

export default store;

After integrating this, You might getting this redux error

Fix:


...
middleware: getDefaultMiddleware =>
    getDefaultMiddleware({
      serializableCheck: false,
    }),
...

🚨 Final Note

By applying this fix, Redux may work as before.
But keep in mind — this is only a temporary workaround.

👉 You should migrate your store setup to Redux Toolkit for long-term stability and compatibility with the new React Native architecture.

📁3. Absolute imports fail

If you’re using absolute import paths like @abc/screens defined in package.json, you may find they don’t resolve properly in the new architecture setup.

🛠️ In my case, I had to temporarily fall back to relative paths like:

import MyScreen from '../../screens/MyScreen';

✅ Later, I fixed this properly by configuring babel.config.js and tsconfig.json.
(I'll walk through that fix in a later section.)

4. Bridging fails

With the New Architecture, React Native introduces a bridge-less communication model.

This means:

Legacy native modules written using the old bridge might stop working.
You must migrate to TurboModules, define spec files, and rely on codegen for typed module integration.

While it’s more strict, it brings better performance, type safety, and native interoperability.

5. GIFs Fail to Load (New Architecture Compatibility)

If your app uses GIFs, they may not work properly with the New Architecture (Fabric/TurboModules).

Fix:

Add the Fresco GIF dependency to app/build.gradle:

implementation 'com.facebook.fresco:animated-gif:3.6.0'

⚠️ Note: If 3.6.0 is not compatible, use the latest stable version of Fresco instead.

6. SafeAreaView Overlaps Status Bar on Android 15+ (Edge-to-Edge Issues)

If your app's content overlaps the status bar or edge-to-edge display isn't working properly on Android 15+, try this solution.

Fix:
Add this line to your Android /android/app/src/main/res/values/styles.xml

<item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>

7. `react-native-linear-gradient` Padding Not Applying

When adding padding directly to the <LinearGradient> component, it won’t work as expected.
Instead, wrap your content in a <View> and apply padding to that <View>.

Fix


<LinearGradient
  colors={[COLORS.COLOR_ED0101, COLORS.COLOR_B60101]}
  style={styles.gradient}
>
  <View style={{paddingHorizontal: 20, paddingVertical: 20}}>
    <Text>Your text</Text>
  </View>
</LinearGradient>

8. Custom Font Not Working on iOS

Some custom fonts may not render correctly on iOS due to font family and weight handling in RCTFontUtils.mm.

Modify the file:

packages/react-native/ReactCommon/react/renderer/textlayoutmanager/platform/ios/react/renderer/textlayoutmanager/RCTFontUtils.mm


if (fontNames.count == 0) {
  font = [UIFont fontWithName:fontProperties.family size:effectiveFontSize];
  if (!font) {
    font = [UIFont systemFontOfSize:effectiveFontSize weight:fontProperties.weight];
  }
} else {
  CGFloat closestWeight = INFINITY;
  for (NSString *name in fontNames) {
    UIFont *fontMatch = [UIFont fontWithName:name size:effectiveFontSize];
    if (RCTGetFontStyle(fontMatch) != fontProperties.style) {
      continue;
    }
    CGFloat testWeight = RCTGetFontWeight(fontMatch);
    if (ABS(testWeight - fontProperties.weight) < ABS(closestWeight - fontProperties.weight)) {
      font = fontMatch;
      closestWeight = testWeight;
    }
  }
  if (!font) {
    font = [UIFont fontWithName:fontNames[0] size:effectiveFontSize];
  }
}

GitHub Reference: PR #47691

Problem	Solution
🌐 i18n Translations not working	Multi-language Setup Guide
⚛️ Redux not working	Redux Integration Tutorial
📁 Absolute imports fail	Absolute Imports Fix
🔌 Native Bridging fails	TurboModules Guide • C++ Guide
🖼️ GIFs not loading	`implementation 'com.facebook.fresco:animated-gif:3.6.0'`
🖼️ Layout overlapping	`<item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>`
🎨 LinearGradient padding issue	Wrap content in `<View>` and apply padding to `<View>` instead of `<LinearGradient>`.
🔠 Custom font not rendering on iOS	Patch `RCTFontUtils.mm` to handle font names and weights more reliably. GitHub Ref

🔧 Platform-Specific Challenges (Android & iOS)

While migrating to the New Architecture, I ran into some platform-specific issues — especially on Android and iOS. Below are the key problems I faced, and how I resolved them.

Android

📦 APK Size Increased

After upgrading to the New Architecture, I noticed the APK size increased significantly:

Version	APK Size
🧓 Before Upgrade	112 MB
🆕 After Upgrade	140 MB

However, with a simple tweak, I was able to bring it down drastically — my final APK was just 65 MB.

⚠️ Important: After applying this change, make sure to test your app’s performance and launch time thoroughly.
There have been community discussions mentioning that setting android:extractNativeLibs="true" might slightly impact launch performance.
In my case, I carefully compared app launch behavior before and after the change — and found no noticeable difference in performance.

✅ Solution

Update your AndroidManifest.xml to include the following inside the <application> tag:

<application
  android:extractNativeLibs="true"
  ...
>

This ensures unused native libraries are not bundled unnecessarily.

🛑 Proguard Build Failure

If you’re using Proguard or enabling minifyEnabled, you may see this common R8 error:

🛠 Fix Steps

1. Open the file:

💡 Note: Make sure to build your release APK first — otherwise, the missing_rules.txt file will not be generated.

android/app/build/outputs/mapping/release/missing_rules.txt

2. Copy the suggested rules from that file.
3. Paste them into android/app/proguard-rules.pro:

# Added from R8 missing rules
-keep class com.example.SomeClass { *; }
-dontwarn com.example.OtherClass

📌 If you already have custom Proguard rules, merge them carefully to avoid breaking your release build.

📝 Reference: React Native GitHub Issue #36505

Android Double Splash issue

Soulution

1. Create a custom splash drawable
Inside your project, create the file:

android/app/src/main/res/drawable/splash_screen.xml

Add the following code:


<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Background that matches React Native splash screen -->
    <item>
        <shape android:shape="rectangle">
            <solid android:color="#000000" />
        </shape>
    </item>

    <!--app logo centered (optional - remove if you just want solid color) -->
    <!-- <item>
        <bitmap
            android:gravity="center"
            android:src="@mipmap/ic_launcher" />
    </item> -->
</layer-list>

2. Update styles.xml

Open android/app/src/main/res/values/styles.xml and add:


<item name="android:windowBackground">@drawable/splash_screen</item>
<item name="android:statusBarColor" tools:targetApi="l">?attr/colorPrimary</item>

This ensures that the splash screen defined in splash_screen.xml is used as the window background, preventing the double splash issue on Android.

🍏 iOS-Specific Setup Issues

While running pod install, I ran into the following CocoaPods and build error:

✅ Solution

Edit your Podfile as follows:

platform :ios, '15.1'          # Add this
use_modular_headers!          # Add this

target 'YourAppName' do
  config = use_native_modules!

  # ——— Add this block ———
  $RNFirebaseAsStaticFramework = true
  use_frameworks! :linkage => :static

  pod 'Firebase', :modular_headers => true
  pod 'FirebaseCoreInternal', :modular_headers => true
  pod 'GoogleUtilities', :modular_headers => true
  pod 'FirebaseCore', :modular_headers => true
  # ——— End ———

  use_react_native!(...)
end

Then run:

cd ios && pod install

This ensures compatibility with Firebase and other modular dependencies when using the new architecture.

iOS Double Splash issue

1. Open LaunchScreen.storyboard
Path: ios/YourApp/LaunchScreen.storyboard

If the file doesn’t exist, create a new LaunchScreen.storyboard in Xcode (File → New → File → User Interface → Storyboard).

2. Set Background Color

Select the main View in Interface Builder.
In the Attributes Inspector, set the Background color (e.g., black #000000 to match Android).

3. Add App Logo (ImageView)

Drag an Image View onto the center of the screen.
In the Attributes Inspector, set the image to your logo (e.g., AppLogo or LaunchIcon).
Use Auto Layout to center it:
- Select the Image View → Add constraints → Horizontally & Vertically in Container.
- Optionally set width/height constraints to keep logo size consistent.

4. Add Logo Asset

Place your splash/logo image inside ios/YourApp/Images.xcassets.
Name it (e.g., AppLogo).
Make sure it has @1x, @2x, and @3x versions for all devices.

5. Set LaunchScreen in Project Settings

In Xcode → Project Navigator → Select your project → General tab.
Under App Icons and Launch Images, set Launch Screen File to LaunchScreen.storyboard.

Example (Storyboard XML snippet)

If you prefer raw XML editing instead of Xcode UI, your LaunchScreen.storyboard could look like this (simplified):


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="18122" targetRuntime="iOS.CocoaTouch" initialViewController="ViewControllerID">
    <scenes>
        <!-- Launch Screen -->
        <scene sceneID="LaunchScene">
            <objects>
                <viewController id="ViewControllerID" sceneMemberID="viewController">
                    <view key="view" contentMode="scaleToFill" id="ViewID" userLabel="LaunchView">
                        <rect key="frame" x="0.0" y="0.0" width="414" height="896"/>
                        <color key="backgroundColor" systemColor="blackColor"/>
                        <subviews>
                            <imageView contentMode="scaleAspectFit" image="AppLogo" translatesAutoresizingMaskIntoConstraints="NO" id="LogoID"/>
                        </subviews>
                        <constraints>
                            <constraint firstItem="LogoID" firstAttribute="centerX" secondItem="ViewID" secondAttribute="centerX" id="c1"/>
                            <constraint firstItem="LogoID" firstAttribute="centerY" secondItem="ViewID" secondAttribute="centerY" id="c2"/>
                        </constraints>
                    </view>
                </viewController>
            </objects>
        </scene>
    </scenes>
</document>

📝 My Recommendation:

If your current version is significantly outdated or your project is complex, start with a fresh React Native project and migrate your code manually. It may take more time initially, but the result is a leaner, faster, and more future-proof application.

If you're planning to upgrade to the New Architecture, here's what I suggest based on your current version gap:

🔁 Scenario 1: Large Version Gap (e.g., RN 0.68 → 0.79)

🧠 Recommendation:
If your current React Native version is significantly outdated, it's best to:

🆕 Start fresh with a clean React Native project, and manually migrate your screens, logic, and assets.

This ensures a smoother transition without the risk of legacy code breaking under the new system.

Yes, it takes a bit more time — but it pays off with a cleaner and more maintainable codebase.

🔄 Scenario 2: Small Version Gap (e.g., RN 0.75 → 0.79)

⚙️ Recommendation:
If the gap between your current version and the latest one is just 2–4 versions, you can safely use the React Native Upgrade Helper or the official upgrade tool.

These tools help you compare file-by-file changes and apply only the necessary updates — saving time while avoiding full rewrites.

✍️ Choose the upgrade approach that matches your project’s stability and complexity. Don’t rush it — test thoroughly before shipping!

✅ Migration Checklist & Tools

Here’s a handy checklist and toolset to help guide your upgrade to the React Native New Architecture:

🧰 Tools You'll Need

Tool	Purpose
🔄 Upgrade Helper	Compare file-by-file differences between RN versions
⚙️ React Native CLI	Create fresh React Native projects
📦 React Native Directory	Check if libraries support the New Architecture (TurboModules/Fabric)

📝 Migration Checklist

🔍 Audit your current React Native version and all dependencies
📱 Update to the latest Android SDK and compile/target versions
🤔 Decide: Upgrade in-place or create a fresh new RN project
🛠 Update your Podfile, build.gradle, and overall project configs
🚀 Enable the New Architecture (app.build.gradle + Podfile flags)
🧬 Migrate native modules to TurboModules (if applicable)
🌐 Switch from i18n-js to react-i18next for translations
⚛️ Update Redux store using @reduxjs/toolkit
📁 Fix absolute imports via babel.config.js and tsconfig.json
📦 Optimize APK size using android:extractNativeLibs="true"
🧪 Test app performance and launch time thoroughly
🔐 Fix Proguard errors using missing_rules.txt
✅ Validate both APK and IPA builds before production release

🚫 Common Mistakes to Avoid

❌ Mistake	⚠️ Why It's a Problem	✅ What To Do
Skipping clean builds	Cached files can cause unexpected crashes or outdated behavior	Run `npx react-native clean` and `./gradlew clean`
Ignoring native code	Legacy native modules may break under the New Architecture	Refactor to TurboModules using proper `spec.ts` and bridging format
Not updating Android/iOS versions	Incompatible SDK versions can break builds	Use `compileSdkVersion = 34` (or latest) and `platform :ios, '15.1'`
Forgetting New Architecture flags	TurboModules/Fabric won’t be enabled just by upgrading	Enable manually in `gradle.properties`, `build.gradle`, and `Podfile`
Using outdated libraries	Many libraries are not compatible with the New Architecture	Check reactnative.directory before installing any library
Ignoring Proguard + release builds	App might crash only in release mode without clear error logs	Test `release` builds early and copy missing rules from `missing_rules.txt` into `proguard-rules.pro`
Testing only on emulators	Emulators don’t reflect real performance, launch time, or device-specific bugs	Always test on real devices (both Android & iOS)
Skipping the docs	Missing official changes can cause implementation mistakes	Follow React Native New Architecture docs

⚠️ Note:

The issues and solutions I’ve shared are based on my specific project setup.
You might face different roadblocks depending on your architecture, packages, and integrations.

Always validate each solution with your own setup, and don’t hesitate to tweak things accordingly.

🎁 Final Checklist Before You Go Live:

✅ Clean build (npx react-native clean & ./gradlew clean)
✅ New Architecture flags enabled (TurboModules, Fabric)
✅ Native modules migrated or verified
✅ Absolute imports working via Babel & tsconfig
✅ Translations updated (i18n-js → react-i18next)
✅ Redux store migrated to @reduxjs/toolkit
✅ Real device testing (Android + iOS)
✅ Proguard rules added from missing_rules.txt
✅ APK & IPA thoroughly tested
✅ Android/iOS SDK versions updated

🙋 Need Help?

Let me know in the comments if you’re stuck or hit something weird — I’d love to help or even update this guide to cover your case.

🔄 Your Turn!

Have you upgraded your React Native version yet?

👉 Share the challenges you faced and how you solved them in the comments.
Let’s build a helpful community knowledge base together! 💬👥

🎯 Final Thoughts

Upgrading to the New Architecture isn’t just about bumping a version — it’s a complete shift in how React Native communicates with native code.

If you're aiming for long-term stability, performance, and scalability, embracing this architecture with a clean slate may be the best move.

🔚 Wrapping Up

Migrating to the New Architecture in React Native isn’t just about flipping a switch — it’s about adopting a modern, more efficient way to build native apps with better performance, maintainability, and future compatibility.

Yes, it comes with its fair share of gotchas, but once you overcome those, the rewards are worth it 🚀

Bridging in React Native with Pure C++ Modules New Architecture 0.79+: A Comprehensive Guide to Cross-Platform

Amit Kumar — Fri, 13 Jun 2025 17:22:29 +0000

Introduction

React Native continues to evolve, and with version 0.79, bridging native code has become more efficient—especially when using Cross-Platform C++ Native Modules. Writing modules in C++ allows you to share platform-agnostic logic between Android and iOS with a single implementation, reducing duplication and improving performance.

In this guide, we'll walk through:

✅ Creating a C++ Turbo Native Module
✅ Configuring Codegen for scaffolding
✅ Implementing native logic once for both platforms
✅ Registering the module in Android & iOS
✅ Testing the module in JavaScript

💡 Why Use Cross-Platform C++?

Before diving into implementation, let’s understand why using C++ for native modules is a game changer:

✅ Single Source of Truth
With C++, you write the logic once and use it across both Android and iOS. No need to duplicate functionality in Kotlin and Swift/Objective-C—this greatly reduces development and maintenance effort.

🚀 Performance Optimized
C++ offers low-level system access and is highly optimized for performance. For CPU-intensive tasks such as encryption, string manipulation, and audio/video processing, C++ outperforms JavaScript and even many high-level native APIs.

🔄 Better Code Sharing
C++ modules can be reused not only between platforms but even across different apps or teams, especially if you’re building SDKs or libraries. This ensures consistency in logic across platforms.

🔒 Leverage Existing C++ Libraries
There’s a vast ecosystem of mature C++ libraries (e.g., OpenCV, SQLite, Boost). By writing C++ modules, you can tap into these without rewriting logic.

🧱 Tightly Integrated with React Native’s New Architecture
TurboModules and the JSI (JavaScript Interface) enable seamless and efficient communication between JS and C++. This means better memory management, faster calls, and lower overhead.

🚀 Step 1: Create the JavaScript Specs

Turbo Native Modules require a specification file (written in TypeScript) that defines the module's interface.

Create a specs folder in your project root.
Add NativeSampleModule.ts with the following:

import { TurboModule, TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  reverseString(input: string): string;
}

export default TurboModuleRegistry.getEnforcing<Spec>('NativeSampleModule');

🔹 Key Notes:

The file must start with Native (e.g., NativeSampleModule.ts).
The Spec interface defines the module's methods.

🚨 Important Note About Spec Files

When creating your spec file (NativeSampleModule.ts), you must:

Keep it as a TypeScript (.ts) file - Don't change it to JavaScript (.js) or Codegen won't process it
Always prefix with "Native" - The filename must start with Native (e.g., NativeSampleModule.ts), otherwise Codegen will ignore it

⚙️ Step 2: Configure Codegen

Update package.json with the following configuration, making sure to replace com.yourpackagename with your actual package name:

"codegenConfig": {
  "name": "AppSpecs",
  "type": "modules",
  "jsSrcsDir": "specs",
  "android": {
    "javaPackageName": "com.yourpackagename.specs"  // ← Replace with your package name!
  }
}

This tells Codegen where to find the specs and how to generate scaffolding

💻 Step 3: Write the C++ Native Module

Create a `shared` Folder

Place it at the same level as android and ios.

Define the Header `(NativeSampleModule.h)`

//shared/NativeSampleModule.h

#pragma once
#include <AppSpecsJSI.h>
#include <memory>
#include <string>

namespace facebook::react {
class NativeSampleModule : public NativeSampleModuleCxxSpec<NativeSampleModule> {
 public:
  NativeSampleModule(std::shared_ptr<CallInvoker> jsInvoker);
  std::string reverseString(jsi::Runtime& rt, std::string input);
};
} // namespace facebook::react

Implement the Module (NativeSampleModule.cpp)


//shared/NativeSampleModule.cpp

#include "NativeSampleModule.h"

namespace facebook::react {
NativeSampleModule::NativeSampleModule(std::shared_ptr<CallInvoker> jsInvoker)
    : NativeSampleModuleCxxSpec(std::move(jsInvoker)) {}

std::string NativeSampleModule::reverseString(jsi::Runtime& rt, std::string input) {
  return std::string(input.rbegin(), input.rend());
}
} // namespace facebook::react

🔹 What’s Happening?

The header declares the module structure.
The implementation reverses a string (shared logic for both platforms).

🤖 Step 4: Register the Module in Android

1. Add `CMakeLists.txt`

Create android/app/src/main/jni/CMakeLists.txt:

cmake_minimum_required(VERSION 3.13)

# Define the library name here.
project(appmodules)

# This file includes all the necessary to let you build your React Native application
include(${REACT_ANDROID_DIR}/cmake-utils/ReactNative-application.cmake)

# Define where the additional source code lives. We need to crawl back the jni, main, src, app, android folders
target_sources(${CMAKE_PROJECT_NAME} PRIVATE ../../../../../shared/NativeSampleModule.cpp)

# Define where CMake can find the additional header files. We need to crawl back the jni, main, src, app, android folders
target_include_directories(${CMAKE_PROJECT_NAME} PUBLIC ../../../../../shared)

2. Update build.gradle

    buildTypes {
        debug {
            signingConfig signingConfigs.debug
        }
        release {
            // Caution! In production, you need to generate your own keystore file.
            // see https://reactnative.dev/docs/signed-apk-android.
            signingConfig signingConfigs.debug
            minifyEnabled enableProguardInReleaseBuilds
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }

+   externalNativeBuild {
+       cmake {
+           path "src/main/jni/CMakeLists.txt"
+       }
+   }
}

3. Register the new Turbo Native Module

The final step is to register the new C++ Turbo Native Module in the runtime, so that when JS requires the C++ Turbo Native Module, the app knows where to find it and can return it.

From the folder SampleApp/android/app/src/main/jni, run the following command:

curl -O https://raw.githubusercontent.com/facebook/react-native/v0.76.0/packages/react-native/ReactAndroid/cmake-utils/default-app-setup/OnLoad.cpp

Then, modify this file as follows:

android/app/src/main/jni/OnLoad.cpp

#include <DefaultComponentsRegistry.h>
#include <DefaultTurboModuleManagerDelegate.h>
#include <autolinking.h>
#include <fbjni/fbjni.h>
#include <react/renderer/componentregistry/ComponentDescriptorProviderRegistry.h>
#include <rncore.h>

+ // Include the NativeSampleModule header
+ #include <NativeSampleModule.h>

//...

std::shared_ptr<TurboModule> cxxModuleProvider(
    const std::string& name,
    const std::shared_ptr<CallInvoker>& jsInvoker) {
  // Here you can provide your CXX Turbo Modules coming from
  // either your application or from external libraries. The approach to follow
  // is similar to the following (for a module called `NativeCxxModuleExample`):
  //
  // if (name == NativeCxxModuleExample::kModuleName) {
  //   return std::make_shared<NativeCxxModuleExample>(jsInvoker);
  // }

+  // This code register the module so that when the JS side asks for it, the app can return it
+  if (name == NativeSampleModule::kModuleName) {
+    return std::make_shared<NativeSampleModule>(jsInvoker);
+  }

  // And we fallback to the CXX module providers autolinked
  return autolinking_cxxModuleProvider(name, jsInvoker);
}

// leave the rest of the file

🍏 Step 5: Register the Module in iOS

To make sure that the iOS app can effectively build the C++ Turbo Native Module, we need to:

Install pods and run Codegen.
Add the shared folder to our iOS project.
Register the C++ Turbo Native Module in the application.

1. Install Pods and Run Codegen.

cd ios
bundle install
bundle exec pod install

2. Add the shared folder to the iOS project

This step adds the shared folder to the project to make it visible to Xcode.

1. Open the CocoPods generated Xcode Workspace.

cd ios
open SampleApp.xcworkspace

2. Click on the `SampleApp` project on the left and select Add files to "Sample App"....

3. Select the `shared` folder and click on Add.

If you did everything right, your project on the left should look like this:

3. Registering the Cxx Turbo Native Module in your app

To register a pure Cxx Turbo Native Module in your app, you need to:

Create a ModuleProvider for the Native Module
Configure the package.json to associate the JS module name with the ModuleProvider class.

The ModuleProvider is an Objective-C++ that glues together the Pure C++ module with the rest of your iOS App.

3.1 Create the ModuleProvider

From Xcode, select the SampleApp project and press ⌘ + N to create a new file.
Select the Cocoa Touch Class template
Add the name SampleNativeModuleProvider (keep the other field as Subclass of: NSObject and Language: Objective-C)
Click Next to generate the files.
Rename the SampleNativeModuleProvider.m to SampleNativeModuleProvider.mm. The mm extension denotes an Objective-C++ file.
Implement the content of the SampleNativeModuleProvider.h with the following:

NativeSampleModuleProvider.h

#import <Foundation/Foundation.h>
#import <ReactCommon/RCTTurboModule.h>

NS_ASSUME_NONNULL_BEGIN

@interface NativeSampleModuleProvider : NSObject <RCTModuleProvider>

@end

NS_ASSUME_NONNULL_END

This declares a NativeSampleModuleProvider object that conforms to the RCTModuleProvider protocol.

Implement the content of the SampleNativeModuleProvider.mm with the following:

NativeSampleModuleProvider.mm


#import "NativeSampleModuleProvider.h"
#import <ReactCommon/CallInvoker.h>
#import <ReactCommon/TurboModule.h>
#import "NativeSampleModule.h"

@implementation NativeSampleModuleProvider

- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params
{
  return std::make_shared<facebook::react::NativeSampleModule>(params.jsInvoker);
}

@end

3.2 Update the package.json

Modify the package.json as it follows:

     "start": "react-native start",
     "test": "jest"
   },
   "codegenConfig": {
     "name": "AppSpecs",
     "type": "modules",
     "jsSrcsDir": "specs",
     "android": {
       "xxxx": "com.xxp.xx"
     },
     "ios": {
        "modulesProvider": {
          "NativeSampleModule":  "NativeSampleModuleProvider"
        }
     }
   },

   "dependencies": {

At this point, you need to re-install the pods to make sure that codegen runs again to generate the new files:

🧪 Step 6: Test in JavaScript

Modify App.tsx:

import React from 'react';
import { Button, SafeAreaView, Text, TextInput, View } from 'react-native';
import SampleTurboModule from './specs/NativeSampleModule';

function App() {
  const [value, setValue] = React.useState('');
  const [reversedValue, setReversedValue] = React.useState('');

  const onPress = () => {
    const revString = SampleTurboModule.reverseString(value);
    setReversedValue(revString);
  };

  return (
    <SafeAreaView>
      <Text>Enter text to reverse:</Text>
      <TextInput value={value} onChangeText={setValue} />
      <Button title="Reverse" onPress={onPress} />
      <Text>Reversed: {reversedValue}</Text>
    </SafeAreaView>
  );
}

export default App;

🎉 Conclusion

You’ve successfully created a cross-platform C++ Turbo Native Module in React Native 0.79!

🔹 Benefits:

✔ Single codebase for Android & iOS
✔ Better performance with C++
✔ Type-safe with Codegen

Try extending this by adding more methods or integrating third-party C++ libraries!

🚀 Happy Coding! 🚀

How to Integrate Redux in React Native with the New Architecture

Amit Kumar — Wed, 11 Jun 2025 16:54:30 +0000

React Native’s New Architecture—powered by Fabric, TurboModules, and Codegen—enhances performance and improves the developer experience. But when it comes to global state management, Redux is still a go-to solution for many developers.

In this guide, we’ll walk through setting up Redux in a React Native project using a clean, scalable, and future-proof structure, fully compatible with the New Architecture.

📦 Step 0: Install Redux Packages

Let’s start by installing the essential Redux packages:

Using npm:

npm install @reduxjs/toolkit react-redux

Or using yarn:

yarn add @reduxjs/toolkit react-redux

@reduxjs/toolkit provides a modern Redux setup with less boilerplate.
react-redux connects your React Native components to the Redux store.

🗂 Folder Structure

We’ll organize Redux inside the src/ folder like this:

/src
  ├── /store
  │   ├── configureStore.js
  │   └── rootReducer.js
  ├── /services
  │   └── /app
  │       ├── reducer.js
  │       └── actions.js (optional)
  └── App.js

⚙️ Step 1: Configure the Store

src/store/configureStore.js

import { configureStore } from '@reduxjs/toolkit';
import rootReducer from './rootReducer';

const store = configureStore({
  reducer: rootReducer,
  devTools: true,
  middleware: getDefaultMiddleware =>
    getDefaultMiddleware({
      serializableCheck: false, // Avoid warnings for non-serializable values like navigation
    }),
});

export default store;

🧠 Step 2: Create Root Reducer

src/store/rootReducer.js

import { combineReducers } from '@reduxjs/toolkit';
import { appReducer } from '../services/app/reducer';

const combinedReducer = combineReducers({
  app: appReducer,
});

const rootReducer = (state, action) => {
  if (action.type === 'USER_LOGOUT') {
    state = undefined;
  }
  return combinedReducer(state, action);
};

export default rootReducer;

This handles app-wide state reset on logout.

Step 3: Create Actions, Constants, and Reducers

Next, create folders and files for actions, constants, and reducers.

Create the following directory structure inside the store folder:

store/
  Home/
    action/
      index.js
    constant/
      index.js
    reducer/
      index.js

Actions
Define your actions in store/Home/action/index.js.

// store/Home/action/index.js
import { TEST_NAME } from '../constant';

export const addValue = (text) => ({
  type: TEST_NAME,
  payload: text,
});

Constants
Define your action types in store/Home/constant/index.js.

// store/Home/constant/index.js
export const TEST_NAME = 'TEST_NAME';

Reducers
Handle the state changes in store/Home/reducer/index.js.

// store/Home/reducer/index.js
import { TEST_NAME } from '../constant';

const initialState = {
  value: '',
};

const inputValueReducer = (state = initialState, action) => {
  switch (action.type) {
    case TEST_NAME:
      return {
        ...state,
        value: action.payload,
      };
    default:
      return state;
  }
};

export default inputValueReducer;

Step 4: Integrate Redux with React Native Components

Now, let's integrate Redux with a React Native component.

Home Screen
Create or modify a screen component to dispatch actions and read state from the Redux store.

// screens/Home.js
import React, { useState } from 'react';
import { Button, StyleSheet, Text, TextInput, View } from 'react-native';
import { useDispatch, useSelector } from 'react-redux';
import { TEST_NAME } from '../../store/Home/constant';

const Home = ({ navigation }) => {
  const [value, setValue] = useState('');
  const text = useSelector((state) => state.inputValueReducer.value);
  const dispatch = useDispatch();

  return (
    <View style={styles.container}>
      <Text onPress={() => navigation.navigate('Profile')}>Home</Text>
      <TextInput value={value} onChangeText={(text) => setValue(text)} style={styles.input} />
      <Button
        title='Send'
        onPress={() => {
          dispatch({ type: TEST_NAME, payload: value });
        }}
      />
      <Text>{text}</Text>
    </View>
  );
};

export default Home;

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  input: {
    borderColor: 'gray',
    borderWidth: 1,
    padding: 10,
    marginBottom: 10,
    width: '80%',
  },
});

Step 5: Wrap Your Application with the Provider

Finally, wrap your application with the Provider component from react-redux to make the Redux store available to your entire app.

// App.js
import React from 'react';
import { Provider } from 'react-redux';
import store from './store/configStore';
import Home from './screens/Home';

const App = () => {
  return (
    <Provider store={store}>
      <Home />
    </Provider>
  );
};

export default App;

Conclusion

By following these steps, you've successfully integrated Redux and Redux-Thunk into your React Native application. This setup provides a scalable architecture for managing state and handling asynchronous operations, making your application more robust and maintainable.

🚀 Automate iOS Builds and Uploads to TestFlight Using Fastlane

Amit Kumar — Tue, 20 May 2025 12:42:51 +0000

In the previous blog, we explored how to integrate Fastlane for Android builds and Firebase App Distribution. Now, moving forward, let's shift gears and focus on the iOS side of automation—specifically, building your iOS app and uploading it to TestFlight using Fastlane.

This guide is perfect for React Native developers who want to streamline iOS releases and reduce manual efforts.

Why Fastlane for iOS?

Fastlane simplifies the complex process of iOS builds and deployments by:

Automating tedious tasks
Reducing human error
Saving hours of manual work
Providing consistent builds every time

🧰 Getting Started with Fastlane for iOS

✅ 1. Install Fastlane

First, install Fastlane using RubyGems:

brew install fastlane

✅ 2. React Native Project Setup (iOS)

Navigate into your iOS directory:

cd ios
fastlane init

You’ll be prompted with the question:

"What would you like to use fastlane for?"

select option 2:
👉 Automate beta distribution to TestFlight

During this initialization process, Fastlane will ask for your iOS bundle identifier (e.g., com.example.app). Once completed, a fastlane directory will be created inside the ios folder

🔐 3. Set Up App-Specific Password for Fastlane

To upload builds to TestFlight, Apple requires an app-specific password. Here’s how to create one:

Visit: Apple.com
Sign in with your Apple Developer account.
Go to Sign-In and Security > App-Specific Passwords
Click Generate an app-specific password, name it (e.g., "fastlane"), and copy the password and paste it in .env file

Then, create a .env file inside the ios/fastlane directory:
Paste the following line:

And once done now paste the password here

FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD=paste_your_password_here

This ensures that Fastlane can authenticate securely when uploading builds to TestFlight.

🔄 Fastlane Configuration (iOS)

Now that the environment is ready, here’s the Fastlane configuration for building your app and uploading it to TestFlight.

default_platform(:ios)

platform :ios do
  desc "Build and upload to TestFlight"
  lane :build_and_upload do

    # Configuration
    app_identifier = "com.xxxx.xxxx.xxx" # Replace with your actual bundle ID
    profile_name = "YOUR PROJECT NAME - Prod Distribution" # Found in Xcode > Signing & Capabilities

    build_ios_app(
      workspace: "YOUR_PROJECT.xcworkspace",
      scheme: "YOUR_SCHEME", # Typically the same as your project name
      export_method: "app-store",
      clean: true,
      export_options: {
        provisioningProfiles: {
          app_identifier => profile_name
        },
        method: "app-store"
      },
      output_directory: "./build",
      output_name: "YOURIPANAME.ipa"
    )

    upload_to_testflight(
      ipa: "./build/YOURIPANAME.ipa",
      skip_waiting_for_build_processing: true,
      changelog: File.read(File.expand_path("../../release_notes.txt", File.dirname(__FILE__)))
    )
  end
end

Make sure to replace the placeholders like:

YOUR_PROJECT.xcworkspace
YOUR_SCHEME
YOURIPANAME.ipa
app_identifier

📜 Creating release_notes.txt

Place this file in your root directory (above ios):

release_notes.txt

Example contents:

🚀 New Features
- Added support for voice recognition
- Improved video playback performance

🐞 Bug Fixes
- Fixed crash on iOS 17 during startup
- Resolved notification issues on background mode

This file is used by Fastlane to add release notes to the TestFlight build.

🚀 Run the Lane

From the project’s ios directory, trigger your automated build and upload:

fastlane build_and_upload

Fastlane will:

Build your iOS app.
Export the .ipa.
Upload it to TestFlight.
Attach your release notes.

💡 Final Tips

🔐 Keep .env out of version control by adding it to .gitignore.
⚙️ Automate the entire flow with CI/CD tools like GitHub Actions or Bitrise.
🧼 Use Fastlane actions like clean_build_artifacts or clear_derived_data for a fresh build.
🧪 Use --verbose flag for debugging when something goes wrong.

🎯 Wrapping Up

By automating your iOS builds and TestFlight uploads with Fastlane, you're saving time, reducing human error, and improving consistency across release cycles.

This setup is a great follow-up to the iOS Fastlane flow, making your entire React Native deployment process fully automated.

🔄 Replacing the Base URL of a Path in JavaScript

Amit Kumar — Fri, 16 May 2025 11:13:59 +0000

In modern web or mobile development, working with dynamic URLs is common — especially when environments (development, staging, production) have different base URLs but share similar API paths. One useful helper function is replacing just the base URL of an existing URL string while preserving its path and query parameters.

Here’s a handy utility function to do just that:

export const replaceBaseUrl = (oldUrl, newUrl) => {
  try {
    const parser = new URL(oldUrl); // Parse the original URL
    const newUrlObject = new URL(parser?.pathname, newUrl); // Replace the base URL while keeping the path
    return newUrlObject?.toString(); // Return the updated URL as a string
  } catch (error) {
    // You can log or handle errors here
    console.error("Invalid URL:", error);
    return null;
  }
};

🔍 How It Works

new URL(oldUrl) is used to safely parse the existing URL.
parser.pathname extracts just the path portion (e.g., /api/user/123).
new URL(pathname, newUrl) creates a new URL with the same path but a new base.
The result is returned as a string using toString().

✅ Example Usage

const oldUrl = 'https://old-api.example.com/api/user/123';
const newBase = 'https://new-api.example.com';

const updatedUrl = replaceBaseUrl(oldUrl, newBase);
console.log(updatedUrl); 
// Output: 'https://new-api.example.com/api/user/123'

⚠️ Error Handling

If an invalid URL is passed, the function catches the error and logs it, returning null.

You can customize the error handling section to suit your needs, such as throwing the error, logging it to a monitoring service, or returning a fallback URL.

🎯 When to Use This

Switching environments dynamically (Dev, QA, Prod)
Migrating to a new domain without changing path structures
Proxying requests in mobile apps
Rewriting URLs for API redirection

Final Thoughts

The replaceBaseUrl function is a small but powerful utility that can simplify how you manage endpoint configurations across multiple environments. Clean, readable, and practical — exactly how utility functions should be.

Let me know if you’d like to expand this into a code snippet component or integrate it with a URL manager service!

React Native: Two-Way Bridging with Android Native Modules

Amit Kumar — Thu, 15 May 2025 15:33:00 +0000

React Native is a powerful framework that enables developers to build mobile apps using JavaScript and React. But what happens when you need to interact with platform-specific code, like accessing native Android features? That’s where Native Modules come into play.

In this blog post, we’ll walk through a simple yet effective example of creating a native module in Android and bridging it with React Native. We’ll:

Call a native method from React Native to get a message
Send data from React Native to the Android side

🧩 Step-by-Step Guide

📁 1. Define Your Interface

Create a Kotlin class called HelloWorldModule.kt inside android/app/src/main/java/com/nativebridging/HelloWorldModule.kt:

package com.nativebridging

import android.util.Log
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.bridge.ReactContextBaseJavaModule
import com.facebook.react.bridge.ReactMethod
import com.facebook.react.bridge.Callback
import com.facebook.react.bridge.ReadableMap

class HelloWorldModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
    override fun getName(): String {
        return "HelloWorld"
    }

    @ReactMethod
    fun sayHello(successCallback: Callback) {
        successCallback.invoke("Hello World from Android!")
    }

    @ReactMethod
    fun receivedData(data: ReadableMap, callback: Callback) {
        Log.d("ReactNative", "Received data: ${data.toString()}")

        val userName = data.getString("userName") ?: "No username"
        val age = data.getString("age") ?: "No age"
        Log.d("ReactNative", "Username: $userName, Age: $age")

        // Send response back to JS
        callback.invoke("Data received successfully")
    }
}

Screenshot for reference

🔍 What's Happening Here?

sayHello: Sends a simple string response to the React Native side.
receivedData: Receives a ReadableMap from React Native and logs the contents, then sends a confirmation back.

📦 Step 2: Register the Native Module with React Native

Create a HelloWorldPackage.kt inside android/app/src/main/java/com/nativebridging/HelloWorldPackage.kt:

package com.nativebridging

import com.facebook.react.ReactPackage
import com.facebook.react.bridge.NativeModule
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.uimanager.ViewManager

class HelloWorldPackage : ReactPackage {
    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
        return listOf(HelloWorldModule(reactContext))
    }

    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
        return emptyList()
    }
}

Screenshot for reference

Then register this package in your `MainApplication.kt` file:

            PackageList(this).packages.apply {
              // Packages that cannot be autolinked yet can be added manually here, for example:
              // add(MyReactNativePackage())
                add(HelloWorldPackage()) // 👈 Add this line
            }

💡 Step 3: Call Native Methods from React Native

Now let's build the React Native part.

App.js (or App.tsx)

import {StyleSheet, View, NativeModules, Button, Alert} from 'react-native';
import React from 'react';

const App = () => {
  const {HelloWorld} = NativeModules;

  const getMessageFromAndroid = () => {
    HelloWorld.sayHello(msg => {
      Alert.alert('Message from Android', msg);
    });
  };

  const sendMessageToAndroid = () => {
    HelloWorld.receivedData(
      {
        userName: 'amit@gmail.com',
        age: '30',
      },
      response => {
        Alert.alert('Android Response', response);
      },
    );
  };

  return (
    <View style={styles.container}>
      <Button
        title="Get Message from Android"
        onPress={getMessageFromAndroid}
      />

      <Button title="Send Data to Android" onPress={sendMessageToAndroid} />
    </View>
  );
};

export default App;

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    gap: 20,
  },
});

📲 What You’ll See in Action

When you tap "Get Message from Android", an alert will pop up with the message "Hello World from Android!".
When you tap "Send Data to Android", the Android logs will print the user data, and an alert will confirm receipt.

🔚 Wrapping Up

With just a few lines of code, you've built a bridge between your JavaScript world and the native Android layer! This is extremely useful for integrating SDKs or platform-specific features that aren’t exposed to React Native out of the box.

✅ Key Takeaways:

Use @ReactMethod in your native module to expose Android functions.
Always register the native module via a ReactPackage.
Use NativeModules in React Native to call native code.

Native modules give React Native superpowers 💥 — start using them to unlock more of what Android has to offer.

iOS Native Modules in React Native: Achieving Two-Way Bridging🚀

Amit Kumar — Wed, 14 May 2025 19:01:39 +0000

Let's dive deep into creating powerful native modules that bridge JavaScript and iOS seamlessly. ✨

🛠️ Step-by-Step: Create a Native Module in Swift

Let’s build a simple module called MyNativeModule that:

Sends data from JS to iOS 📤
Sends events from iOS to JS 📩

1️⃣ Create MyNativeModule.swift (Swift) 💻

📄 File: MyNativeModule.swift

import Foundation
import React

@objc(MyNativeModule)
class MyNativeModule: RCTEventEmitter {

  // MARK: - JS → iOS
  @objc
  func receivedData(_ params: NSDictionary, callback: RCTResponseSenderBlock) {
    print("📦 Received from JS:", params)
    // callback(["✅ iOS received your data!"])
  }

  // MARK: - iOS → JS
  @objc
  func triggerMessageToRN() {
    let eventData: [String: Any] = ["message": "👋 Hello from iOS! 🎉"]
    sendEvent(withName: "onMessageFromNative", body: eventData)
  }

  // MARK: - Required Overrides
  override func supportedEvents() -> [String] {
    return ["onMessageFromNative"]
  }

  override static func requiresMainQueueSetup() -> Bool {
    return true
  }
}

📝 This class extends RCTEventEmitter to support two-way communication.

2️⃣ Create Objective-C Bridge (`MyNativeModule.m`) 🔌

Even though you’re using Swift, React Native still requires an Objective-C header to expose the module to JS.

📄 File: MyNativeModule.m

#import <Foundation/Foundation.h>
#import <React/RCTBridgeModule.h>

@interface RCT_EXTERN_MODULE(MyNativeModule, NSObject)

RCT_EXTERN_METHOD(receivedData:(NSDictionary *)params callback:(RCTResponseSenderBlock)callback)
RCT_EXTERN_METHOD(triggerMessageToRN:(NSDictionary *)params callback:(RCTResponseSenderBlock)callback)
@end

🔗 This bridges Swift methods to the RN JS runtime.

🧠 Using the Native Module in JS (React Native Side)

Let’s test our newly created native module in a sample React Native app:

📄 File: App.js

import React, {useEffect} from 'react';
import {
  StyleSheet,
  View,
  Text,
  Button,
  NativeModules,
  NativeEventEmitter,
} from 'react-native';

const {MyNativeModule} = NativeModules;
const eventEmitter = new NativeEventEmitter(MyNativeModule);

const App = () => {
  useEffect(() => {
    const subscription = eventEmitter.addListener(
      'onMessageFromNative',
      data => {
        console.log('📨 Message from iOS:', data.message);
      }
    );

    return () => subscription.remove();
  }, []);

  const sendDataToiOS = () => {
    MyNativeModule.receivedData(
      { userName: 'amit@gmail.com', age: '29' },
      response => console.log('✅ Callback from iOS:', response)
    );
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>🚀 React Native + Swift Bridge</Text>
      <Button title="📤 Send Data to iOS" onPress={sendDataToiOS} />
      <Button
        title="📨 Receive Event from iOS"
        onPress={() => MyNativeModule.triggerMessageToRN()}
      />
    </View>
  );
};

export default App;

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
  },
  title: {
    fontSize: 20,
    marginBottom: 20,
    fontWeight: 'bold',
  },
});

✅ Results

🧪 Try it out:

Tap Send Data to iOS → Check Xcode logs for received data.
Tap Trigger iOS to JS → Watch for JS console logs like 📨 Message from iOS: Hello from iOS! 🎉.

⚙️ Troubleshooting Tips

✅ Clean your build folder (Cmd + Shift + K)
✅ Make sure RCT_EXTERN_MODULE is present
✅ Check that Swift is correctly initialized in your project
✅ Use use_frameworks! in your Podfile for Swift support

🏁 Final Thoughts

It easier and faster to bridge native code with JavaScript. With TurboModules, native communication is now more optimized and type-safe.

💡 Whether you’re building a native camera module, voice recognition, or secure authentication — the same pattern applies.

💬 Drop a Comment
Was this guide helpful? Stuck somewhere?
Drop a comment below👇

🔁 Don’t forget to like and share to help others in the RN community!

🚀 How to Enable Over-the-Air (OTA) Updates in React Native Using Stallion

Amit Kumar — Sun, 11 May 2025 20:36:43 +0000

Keeping your app users up-to-date instantly is easier than ever with Stallion — a powerful tool for Over-the-Air (OTA) updates in React Native. Forget waiting for app store approvals; push updates directly to your users with zero friction. 🙌

This guide walks you through setting up Stallion and publishing your first OTA update.

🚀 Why Use Stallion?

✅ Built-in Testing Framework to validate updates before production
🔁 Switch Between App Versions without rebuilding native code
📦 Publish Bundles Instantly using Stallion CLI
📲 Apply Updates In-App using the Stallion SDK
🔄 Manual + Automatic Rollbacks with real-time rollback insights
📊 Detailed Analytics for update adoption and performance tracking
🏷️ Extensive Free Plan for indie devs and small teams
✅ Production-Ready and trusted by teams shipping millions of updates

🔧 Step 1: Set Up Your Stallion Account

To get started with Stallion, you'll first need to create a free account and set up your project.

✅ Create Your Stallion Account

👉 Go to the Stallion Dashboard
Sign up or log in to your account.

🧱 Create a New Project
Once you're signed in, you'll be guided through the process of creating your first project.

Dashboard View
You'll land on the dashboard after logging in:

Click “Create Project”
Hit the "Create Project" button to get started:

Fill in Your Project Details
Enter your project name and description, then click "Create":

Project Successfully Created
You'll now see your new project listed in the dashboard, Now Click on the project card to proceed.

🗂️ Create a New Bucket
Now, let’s set up a storage bucket for your project.

Bucket View – Click "Create Bucket"
Navigate to the Buckets section and click on "Create Bucket":

Create New Bucket
Fill in the necessary details to create your new bucket:

You're now ready to start integrating your application with Stallion! 🎉

📦 Step 2: Install the Stallion CLI

Install the CLI to interact with Stallion from your terminal.

# Using npm
npm install --save-dev stallion-cli

# Or using Yarn
yarn add -D stallion-cli

📲 Step 3: Install the Stallion SDK

Add the Stallion SDK to your React Native project:

# Using npm
npm install react-native-stallion

# Or using Yarn
yarn add react-native-stallion

Then, install CocoaPods for iOS:

npx pod-install

🧩 Step 4: Configure Native Projects

🤖 Android Configuration

ℹ️ For React Native < 0.76

In MainApplication.java, update getJSBundleFile:

// ...other imports
import com.stallion.Stallion;

public class MainApplication extends Application implements ReactApplication {
  // ...rest of the class
  @Override
  protected String getJSBundleFile() {
      return Stallion.getJSBundleFile(getApplicationContext());
  }
}

ℹ️ For React Native > 0.76

In MainApplication.kt, update the reactNativeHost:

// ...other imports
import com.stallion.Stallion

// ...other functions
override val reactNativeHost: ReactNativeHost =
  object : DefaultReactNativeHost(this) {
    override fun getPackages(): List<ReactPackage> =
      //other methods...

      override fun getJSBundleFile(): String? {
          return Stallion.getJSBundleFile(applicationContext)
      }
  }

If running on React Native 82 and above

Inside MainApplication.kt file, override the reactHost property:

MainApplication.kt

// ...other imports
import com.facebook.react.ReactHost
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
import com.stallion.Stallion

class MainApplication : Application(), ReactApplication {
  override val reactHost: ReactHost by lazy {
    getDefaultReactHost(
      context = applicationContext,
      packageList = 
                PackageList(this).packages.apply {
                    // Packages that cannot be autolinked yet can be added manually here, for example:
                    // add(MyReactNativePackage())
                },
               Add this link -> jsBundleFilePath = Stallion.getJSBundleFile(applicationContext)
    )
  }
}

🍎 iOS Configuration

ℹ️ For React Native < 0.76

In AppDelegate.mm, update the sourceURLForBridge method:

// ...other imports
#import "StallionModule.h"

@implementation AppDelegate
// ...other implemetations
- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
    #if DEBUG
      return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
    #else
      return [StallionModule getBundleURL];
    #endif
}

ℹ️ For React Native > 0.76

In AppDelegate.swift, update the bundleURL() method:

// ...other imports
import react_native_stallion

// ...other functions
override func bundleURL() -> URL? {
    #if DEBUG
        RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
    #else
        StallionModule.getBundleURL()
    #endif
}

ℹ️ For React Native 82 and above

#if DEBUG
    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
#else
    return StallionModule.getBundleURL()

🔐 Step 5: Add Project ID and App Token

Add your Stallion credentials to platform-specific config files.

iOS `(Info.plist):`

Add below code on Info.plist file

<key>StallionProjectId</key>
<string>your_project_id</string>
<key>StallionAppToken</key>
<string>your_app_token</string>

Android `(res/values/strings.xml)`:

Add below code on strings.xml file

<string name="StallionProjectId">your_project_id</string>
<string name="StallionAppToken">your_app_token</string>

You can generate your app token in the Stallion dashboard:

Click on Generate App Token button in order to get app token

🔍 Find your Project ID and App Token under Project Settings in the Stallion Dashboard.

🧵 Step 6: Wrap Your App Component

In your App.js or App.tsx, wrap your root component with the withStallion HOC:

import { withStallion } from 'react-native-stallion';
// rest of your code
export default withStallion(App);

📦 Step 7: Create a Release Build

Android:

# macOS
./gradlew assembleRelease

# Windows
gradlew.bat assembleRelease

iOS:

Use Xcode to archive and export a release build (IPA).

Install the build on a device or emulator to test.

🧪 Step 8: Make a Code Change

Modify your app’s logic or UI—for example, update some text—and save your changes.

🚚 Step 9: Publish the OTA Update

1. Login to Stallion CLI:

npx stallion login

This will open a browser window for authentication. Once logged in, copy and paste the token back into your terminal.

2. Publish the update:
Use the appropriate command below to publish your update for Android or iOS.

🤖 Android Command

npx stallion publish-bundle \
  --upload-path=orgname/project-name/bucket-name \
  --platform=android --release-note="notes"

🍎 iOS Command

npx stallion publish-bundle \
  --upload-path=orgname/project-name/bucket-name \
  --platform=ios --release-note="notes"

🔍 Replace orgname, project-name, and bucket-name with your actual values.

Or use "Copy Bundle Path" from the dashboard in order to get the orgname/project-name/bucket-name:

📤 Step 10: Promote and Release the Bundle

Follow these steps to promote your Android (and iOS) bundle from staging to production.

✅ Step 1: Access the Bundle Details

Navigate to the Stallion Dashboard
Click on the View Details button.

✅ Step 2: Open the Android Bundles Tab

Click on the Android Bundles tab in the navigation bar.

✅ Step 3: Add Release Notes and Promote

After clicking, a new box will appear.
Enter your release notes.
Click on Promote Bundle.

✅ Step 4: Select Target Version & Finalize Promotion

In the Promote Bundle View, choose the target version.
Add the release notes again.
Click on Promote.

✅ Step 5: Manage the Release

Once promoted, click on the Manage Release button.

✅ Step 6: Publish to Production

Add the release notes.
Set rollout percentage to 100%.
Click on Publish Changes.

🍎 The same steps should be followed for iOS as well.

🎉 All Done!

Your bundle has been successfully promoted and released.

To view the latest changes in the app:
Kill (close) the app completely, then
Reopen the app to load the updated JS bundle.
This ensures the latest changes are reflected properly.

🔁 If not, try staying in the app for at least a minute before closing it. Then reopen it — your changes should now be visible.

✅ Final Thoughts

Stallion makes the OTA update process seamless and efficient. With minimal setup and a powerful CLI, you can roll out bug fixes, feature updates, or UI tweaks instantly—keeping your app fresh and users happy.

Ready to streamline your React Native deployment?
Start using Stallion today and revolutionize your mobile development workflow.