Onboarding: ptmt/react-native-macos

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ptmt/react-native-macos shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 2y ago

• 12 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ptmt/react-native-macos repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ptmt/react-native-macos.

What it runs against: a local clone of ptmt/react-native-macos — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ptmt/react-native-macos | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 843 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>ptmt/react-native-macos</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ptmt/react-native-macos. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ptmt/react-native-macos.git
#   cd react-native-macos
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ptmt/react-native-macos and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ptmt/react-native-macos(\\.git)?\\b" \\
  && ok "origin remote is ptmt/react-native-macos" \\
  || miss "origin remote is not ptmt/react-native-macos (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 843 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~813d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ptmt/react-native-macos"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

react-native-macos is a fork of React Native that enables building native macOS desktop applications using React and JavaScript. It transpiles React components into Cocoa-based native code, allowing developers to write cross-platform code that runs on both iOS and macOS without learning Swift or Objective-C. Traditional React Native fork structure: core bridge bindings in Objective-C++ (Libraries/), JavaScript bindings in Libraries/ subdirectories (ART, Animated, etc.), integration tests in IntegrationTests/, ContainerShip Docker setup for CI, Xcode project files (.xcodeproj), and Buck build system configuration. No monorepo—single unified codebase.

Who it's for

JavaScript/React developers who want to build macOS desktop applications without learning Cocoa or Objective-C, particularly those already familiar with React Native for iOS and wanting to extend their codebase to desktop.

Maturity & risk

This project is deprecated and unmaintained as of the README notice—it explicitly recommends Microsoft's React Native for Windows instead. There is no recent CI activity visible (CircleCI config present but stale), and the project lacks active commits. Do not use for new production applications.

Critical risk: officially deprecated. The maintainer (@ptmt) has stopped active development. Single-maintainer project with no handoff documented. The codebase depends on legacy React Native patterns (Node 4.x era, Babel 5) and will likely have unpatched security/compatibility issues. Forking React Native itself introduces high maintenance burden for macOS-specific bugs.

Active areas of work

Nothing—the project is abandoned. The README explicitly states deprecation in favor of Microsoft's React Native Windows and React Native Catalyst. Last meaningful activity likely pre-2018.

Get running

⚠️ Not recommended for new projects. Historical reference only:

npm install react-native-macos-cli -g
react-native-macos init MyProject
cd MyProject
react-native-macos run-macos

Requires: Node 4.x+, macOS 10.11+, Xcode.

Daily commands:

cd MyProject
react-native-macos run-macos

Alternatively, open the generated .xcodeproj in Xcode and build the RCTTesterApp or RNTesterApp targets. See IntegrationTests/ for test harness examples.

Map of the codebase

• .buckconfig: Build system configuration—defines how the entire project is compiled; changes here affect all targets
• Libraries/ART/ART.xcodeproj/project.pbxproj: Core Xcode project definition for the ART rendering library; shows how native modules are wired
• IntegrationTests/IntegrationTestsApp.js: Main test harness for verifying platform-specific React Native features work on macOS
• .circleci/config.yml: CI pipeline config (now stale); reveals original test/build strategy
• ContainerShip/Dockerfile.javascript: Docker image definition for JavaScript test environment; historical reference for dev setup
• Libraries/Animated/: Animation framework ported from React Native; core primitive for many UI patterns

How to make changes

For React component additions: modify Libraries/Components/ subdirectories (mirrors iOS structure). For native platform code: edit .m/.mm files in Libraries/ (e.g., Libraries/ART/ART.xcodeproj/project.pbxproj for build config). For global config: see rn-cli.config.js pattern in README gist. For testing: add cases to IntegrationTests/ directory following the pattern of IntegrationTests/*Test.js.

Traps & gotchas

Critical: Project is unmaintained—do not expect bug fixes or compatibility with modern Node/Xcode. Node 4.x requirement is ancient (security risk). Buck build system is non-standard; most modern React Native uses CocoaPods. Babel 5 (in Animated config) is deprecated—will fail on modern JSX syntax. No lockfile visible (no yarn.lock or package-lock.json in structure)—dependency versions float and may break. macOS 10.11+ requirement excludes modern system features; Catalina+ may have compatibility issues. Xcode version constraints likely strict and undocumented.

Concepts to learn

• Objective-C++ Bridge — This codebase crosses the JavaScript-to-native boundary via Objective-C++ files (.mm); understanding how React Native marshals data between the JavaScript engine and Cocoa APIs is essential to adding native features
• React Native Yoga Layout Engine — macOS UI layout is powered by Yoga (a cross-platform flex layout library), not the native Cocoa auto-layout; this determines how Views calculate size and position
• Declarative vs. Imperative UI — React Native's core paradigm—components declare desired UI state, and the runtime diffuses changes to native code; this differs from traditional Cocoa's imperative UIView manipulation
• Shadow Tree / Virtual DOM Reconciliation — React Native maintains a lightweight JavaScript-side representation of the UI tree and syncs it to native views only on changes; critical to performance and debugging
• Module Registration & Native Turntable — React Native exports native modules via a registry; adding macOS-specific modules requires proper registration in the bridge's turntable (RCTBridge in Cocoa)
• Buck Build System — This repo uses Facebook's Buck (not Xcode alone) for reproducible builds; .buckconfig and BUCK files define how C++/Objective-C++ binaries are linked and distributed

Related repos

• microsoft/react-native-windows — Official replacement—Microsoft's actively maintained React Native fork for Windows and macOS (via Catalyst); recommended by this repo's own README
• facebook/react-native — The upstream React Native project this fork is based on; source of all iOS patterns and core bridges
• react-native-community/react-native-macos — Community fork that may have picked up maintenance after ptmt/react-native-macos was abandoned
• CocoaPods/Specs — Dependency resolution system used by modern React Native projects; this repo predates widespread CocoaPods adoption in RN
• facebook/buck — The build system this project configures in .buckconfig; understanding Buck is required for modifying build targets

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add macOS-specific integration tests for native module bridging

The repo has an extensive IntegrationTests/ directory with tests for Android/iOS features (AccessibilityManager, AsyncStorage, WebSocket, etc.), but no macOS-specific tests. Since this is a Cocoa-based fork, adding macOS-native bridge tests would validate the core platform-specific functionality that differentiates this from upstream React Native.

• [ ] Create IntegrationTests/macOSNativeBridgeTest.js to test Objective-C bridge communication
• [ ] Create IntegrationTests/macOSWindowTest.js to test NSWindow integration and lifecycle
• [ ] Create IntegrationTests/macOSEventTest.js to test macOS-specific events (window focus, minimize, etc.)
• [ ] Update IntegrationTests/IntegrationTestsApp.js to include these tests in the test runner

Create GitHub Actions CI workflow for macOS builds (replacing deprecated Travis CI)

The repo uses Travis CI (referenced in README badge), but GitHub Actions is now the standard for GitHub repos. The .circleci/ directory exists but is for Android. Adding a .github/workflows/macos-build.yml would provide automated builds on every PR without external CI service dependencies.

• [ ] Create .github/workflows/macos-build.yml with xcode build job
• [ ] Add steps to install Node 4.x+ and macOS 10.11+ SDK
• [ ] Include Buck build configuration using .buckconfig
• [ ] Add status badge to README.md pointing to GitHub Actions instead of Travis

Document and add tests for Libraries/ART macOS rendering differences

The Libraries/ART/ directory contains macOS-specific implementations (ARTSurfaceView.m, ARTGroup.m, etc.) for vector graphics, but there are no corresponding integration tests or documentation on how these differ from iOS/Android. This is critical for contributors working on platform-specific rendering.

• [ ] Create IntegrationTests/ARTmacOSRenderTest.js to test shape rendering, gradients, and text
• [ ] Create CONTRIBUTING.md section documenting Libraries/ART/ architecture for macOS
• [ ] Add unit tests in Libraries/ART/ for ARTSurfaceView.m and ARTText.m (currently untested)
• [ ] Document expected visual output differences between iOS and macOS ART rendering

Good first issues

• Add test coverage for macOS-specific lifecycle events in IntegrationTests/AppEventsTest.js—currently mirrors iOS tests but macOS window/focus events are untested.
• Document the exact Xcode + Node + macOS version matrix required; the README.md says 'Node 4.x+, OS X 10.11+' but doesn't specify tested versions or known incompatibilities.
• Port animation tests from Libraries/Animated/ into IntegrationTests/ as a dedicated test module (similar to TimersTest.js, LayoutEventsTest.js)—currently Animated is built but never integration-tested on macOS.

Top contributors

• @ptmt — 41 commits
• @aleclarson — 41 commits
• @Pagebakers — 5 commits
• @rianniello — 3 commits
• @dependabot[bot] — 2 commits

Recent commits

• 1bb1d25 — Merge pull request #278 from ptmt/dependabot/npm_and_yarn/qs-6.5.3 (ptmt)
• 6af5826 — chore(deps): bump qs from 6.5.2 to 6.5.3 (dependabot[bot])
• 0f09ff4 — Merge pull request #255 from ptmt/dependabot/npm_and_yarn/lodash-4.17.19 (ptmt)
• bd550aa — chore(deps): bump lodash from 4.17.15 to 4.17.19 (dependabot[bot])
• 04ce3d2 — Update README.md (ptmt)
• 65d1c81 — Update yargs (ptmt)
• d85636c — Upgrade some deps (ptmt)
• 824ffd3 — Upgrade some deps (ptmt)
• 0f0d7ae — Update yarn.lock (ptmt)
• 546717c — fix: respect layer transforms in UIManager.measure (aleclarson)

Security observations

• High · Deprecated and Unmaintained Project — README.md, Package.json. The project is explicitly marked as deprecated and no longer maintained. This means no security patches, bug fixes, or updates will be provided. Using deprecated software in production environments poses significant security risks. Fix: Migrate to the actively maintained Microsoft React Native Windows version (https://microsoft.github.io/react-native-windows/) or use React Native on Catalyst for macOS development.
• High · Outdated Dependencies with Known Vulnerabilities — package.json (devDependencies section). The package.json contains significantly outdated dependencies: babel-core@5.8.25, babel-loader@5.3.2, webpack@1.11.0, and gulp@3.9.0. These versions are from 2015-2016 and have accumulated security vulnerabilities. Babel 5 reached end-of-life in 2015 and webpack 1 is no longer supported. Fix: Update all dependencies to their latest stable versions: babel-core to 7.x+, webpack to 5.x+, gulp to 4.x+. Run 'npm audit' to identify and fix known vulnerabilities.
• High · fbjs Dependency Vulnerability Risk — package.json (dependencies section). The fbjs@^0.2.1 dependency is extremely outdated (from 2015). This Meta/Facebook utility library may contain unpatched security vulnerabilities. The caret (^) allows any version up to 0.3.0, but the specified baseline is ancient. Fix: Update fbjs to the latest version available. Check current fbjs releases and update the dependency. Consider if fbjs is still necessary for modern React applications.
• Medium · Missing Security Configuration Files — Repository root. No evidence of security-related configuration files such as SECURITY.md, .snyk, or dependabot configuration. This indicates lack of proactive security monitoring and vulnerability management. Fix: Add SECURITY.md with responsible disclosure policy, enable GitHub Dependabot for automated dependency updates, and implement automated security scanning in CI/CD pipeline.
• Medium · Insufficient CI/CD Security Hardening — .circleci/config.yml, ContainerShip/Dockerfile.*. The CircleCI configuration and Dockerfile references suggest basic CI/CD setup, but without visibility into the actual .circleci/config.yml and Dockerfile contents, security best practices cannot be verified (e.g., no signed commits, artifact scanning, secrets management). Fix: Review CI/CD configuration for: secrets management (use CircleCI contexts), container image scanning, signed commits, artifact verification, and principle of least privilege in build environment.
• Medium · Docker Container Risks — ContainerShip/Dockerfile.android, ContainerShip/Dockerfile.android-base, ContainerShip/Dockerfile.javascript. Multiple Dockerfiles exist for Android testing, but without content visibility, potential risks include: outdated base images, missing security updates, credentials in build layers, and insecure Docker practices. Fix: Scan Docker images for vulnerabilities using tools like Trivy or Grype. Use minimal base images (alpine), implement multi-stage builds, avoid secrets in Dockerfiles, and scan for CVEs in base images.
• Low · WebSocket Server Integration Test Without Security Context — IntegrationTests/websocket_integration_test_server.js, IntegrationTests/launchWebSocketServer.command. The file 'websocket_integration_test_server.js' and 'launchWebSocketServer.command' suggest WebSocket testing infrastructure. Without inspecting the code, potential risks include unencrypted connections or missing input validation. Fix: Ensure WebSocket server uses WSS (WebSocket Secure) in production, implements proper authentication, validates all input, and includes rate limiting. Review the server code for injection vulnerabilities.
• Low · Missing .env.example or Secrets Management Documentation — Repository root. No visible documentation for managing environment variables or secrets configuration, increasing risk of accidental credential commits. Fix: Create .env.example template documenting required secrets, add to .gitignore, implement pre-commit hooks to prevent secret commits, and use tools like git-secrets or detect-secrets.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.