RFC: Compiler API

text/0003-compiler-apis.md

@@ -0,0 +1,46 @@
+---
+Feature Name: compiler-apis
+Start Date: 2025-04-30
+RFC PR: https://github.com/rescript-lang/rfcs/pull/3
+ReScript Issue: (leave this empty)
+---
+
+## Summary
+
+Define and standardize a programmatic API surface for the ReScript compiler to enable consistent and reliable integration across tools and environments.
+
+## Motivation
+
+Currently, ReScript lacks a stable, documented programmatic interface.
+
+As a result, most tooling around ReScript—such as editors, external build systems, and web-based tools—depend on reverse-engineered knowledge or tight coupling to the compiler's internal implementation details. This approach is fragile, difficult to maintain, and prone to breakage with compiler updates.
+
+For instance:
+
+- Some projects vendor large parts of the compiler source to extract basic capabilities like parsing or type-checking.
+- Some projects implement custom CLI wrappers to invoke the compiler in subprocesses and then parse its output—an error-prone strategy that limits interactivity and flexibility.
+- Building browser-based tools like the ReScript Playground is particularly challenging, since the compiler is not designed for use in non-Node.js environments. This forces projects to either patch or rebuild the compiler entirely.
+
+A stable, documented, and minimal programmatic API would simplify these use cases, encourage ecosystem innovation, and reduce duplication of effort across the community.
+
+## Detailed design
+
+### Metadata
+
+`rescript` entry provides locations of executable binaries.
+
+```resi
+let version: string
+```
+
+### Compiler entry
+
+`rescript/compiler` entry provides interfaces for the standalone compiler instance.
+
+### Parser entry
+
+`rescript/parser` entry provides interfaces for the standalone parser instance.
+
+### The LSP entry
+
+`rescript/lsp` entry provides interfaces for the standalone parser instance.