feat: allow opting out of tree-sitter & RaTeX downloads via package.json

[eszlamczyk]

What/Why?

Consumers can now skip the heavy install-time native asset downloads (tree-sitter grammars ~169 MB, RaTeX XCFramework ~47 MB, added in #660) when they don't use code highlighting and/or LaTeX math. Following Reanimated's convention, the opt-out is a declarative block in the consumer's own package.json:

{
  "enriched-markdown": {
    "enableCodeHighlight": false,
    "enableMath": false
  }
}

Both fields default to true (opt-out, not opt-in), and are read from the consumer project only (via INIT_CWD), so
there's no effect on this repo's own monorepo development.

Two parts:

1. Gate the downloads (postinstall.mjs) — reads the enriched-markdown block from ${INIT_CWD}/package.json and skips
   the grammar and/or RaTeX download accordingly; early-exits when both are disabled. Any resolution failure (no INIT_CWD, malformed JSON, missing key) falls back to downloading everything — a skipped download is cheaper to recover from than a silently missing feature.
2. Native build keys off asset presence — so a single package.json edit builds cleanly with no Podfile / gradle.properties change required. Previously, skipping a download while the build flag stayed enabled broke the build (the iOS podspec raised on the missing RaTeX XCFramework; iOS/Android fed absent grammar sources to the compiler). Now:

• ReactNativeEnrichedMarkdown.podspec — enable_math is three-state: ENRICHED_MARKDOWN_ENABLE_MATH=0 off, =1 on (keeps the missing-framework raise as a force-on safety net), unset → tracks whether the framework was downloaded, with a Pod::UI.warn when auto-disabled.
• code_highlight_podspec.rb — returns the no-op stub when the vendored tree-sitter runtime is absent.
• android/build.gradle — enableCodeHighlight defaults to vendor-runtime presence when the enrichedMarkdown.enableCodeHighlight gradle property is unset; the property still overrides.

Existing ENRICHED_MARKDOWN_ENABLE_* env / enrichedMarkdown.enable* gradle overrides are unchanged. Android math is unaffected (it uses a Maven dependency, not the vendored XCFramework).

Testing

Built the real publish tarball (npm pack) and installed it into throwaway /tmp consumer projects with different

Verified the native-side auto-disable against the installed layouts:

• iOS code-highlight podspec (real require): assets absent → enabled=false, 0 sources; present → enabled=true, 26
  sources, ENRICHED_MARKDOWN_CODE_HIGHLIGHT=1.
• iOS math resolution: absent + env unset → off (+warn); present → on; absent + =1 → on then raise.
• Android enableCodeHighlight default: absent → false, present → true.

Also ran postinstall.mjs directly against a published-layout sandbox across all config permutations (no key / both off / each off / malformed JSON / no INIT_CWD) — all gate as designed. ruby -c clean on both podspecs.

PR Checklist

• Code compiles and runs on iOS
• Code compiles and runs on Android
• Updated documentation/README if applicable
• Ran example app to verify changes
• E2E tests are passing
• Required E2E tests have been added (if applicable)

[Copilot]

Pull request overview

Adds a consumer-controlled opt-out mechanism to skip downloading large native assets (tree-sitter grammars/runtime and the iOS RaTeX XCFramework) during install, while keeping native builds working by auto-disabling features when assets aren’t present.

Changes:

• Read "enriched-markdown" config from the consumer app’s package.json (via INIT_CWD) in postinstall.mjs to conditionally skip tree-sitter and/or RaTeX downloads.
• Make iOS/Android native build logic default feature enablement based on vendored asset presence, so “skipped download” doesn’t break builds.
• Update docs/README to document the opt-out configuration and revised recovery/behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Documents the new package.json opt-out and links to native-asset instructions.
packages/react-native-enriched-markdown/ReactNativeEnrichedMarkdown.podspec	Makes iOS math enablement track RaTeX presence (unless forced by env) and warns when auto-disabled.
packages/react-native-enriched-markdown/postinstall.mjs	Reads consumer package.json to skip downloading optional native assets.
packages/react-native-enriched-markdown/android/build.gradle	Defaults Android code highlighting enablement based on vendored asset presence unless a Gradle property overrides.
packages/core/cpp/highlight/code_highlight_podspec.rb	Falls back to the disabled/no-op highlight stub when the vendored runtime isn’t present.
docs/NATIVE_ASSETS.md	Adds “Skipping the download (opt out)” section and updates recovery guidance.
docs/LATEX_MATH.md	Documents skipping the RaTeX download via package.json and the new iOS auto-disable behavior.
docs/CODE_HIGHLIGHT.md	Documents skipping grammar downloads via package.json and points to native assets docs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.