From de98bb017e5f64c2b0a4315a5ccb7c2713eade4a Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Fri, 24 Apr 2026 17:47:35 -0400 Subject: [PATCH 1/5] docs: add measured AI workflow messaging Tone down the landing page AI copy so it stays closer to the existing positioning while still calling out coding-agent workflows. Add a linked guide page for the follow-on explanation without changing the homepage hero copy. --- app/routes/LandingPage.res | 158 +++++++++++------- .../docs/manual/agentic-workflows.mdx | 33 ++++ 2 files changed, 131 insertions(+), 60 deletions(-) create mode 100644 markdown-pages/docs/manual/agentic-workflows.mdx diff --git a/app/routes/LandingPage.res b/app/routes/LandingPage.res index b784ebf3a..248db258a 100644 --- a/app/routes/LandingPage.res +++ b/app/routes/LandingPage.res @@ -85,6 +85,12 @@ export {
+
+

{React.string("Readable in. Predictable out.")}

+

+ {React.string(`Readable source, predictable output, and fast compiler feedback are useful whether changes come from a person or a coding agent. ReScript keeps the edit-review-fix loop tight for both humans and tools.`)} +

+
// Playground widget
{
-

{React.string("Quick Install")}

-
- {React.string( - "You can quickly add ReScript to your existing JavaScript codebase via npm / yarn:", - )} -
{copyBox("npm install rescript")}
{React.string("Or generate a new project from the official template with npx:")} @@ -269,26 +269,15 @@ module QuickInstall = { @react.component let make = () => {
-
- //---Textblock on the left side--- -
-

- - {React.string(`Leverage the full power`)} - - {React.string(` of JavaScript in a robustly typed language without the fear of \`any\` types.`)} -

-
- //spacing between columns -
-

- {React.string(`ReScript is used to ship and maintain mission-critical products with good UI and UX.`)} -

-
+
+
+
+

{React.string("Quick Install")}

+

+ {React.string(`You can quickly add ReScript to an existing JavaScript codebase in minutes. That low setup overhead also makes it easy to experiment in fast-moving teams, including ones trying AI-assisted workflows.`)} +

+
+
@@ -379,22 +368,7 @@ module MainUSP = { media={} - paragraph={<> -

- {React.string(`ReScript cares about a consistent and fast - feedback loop for any codebase size. Refactor code, pull complex changes, - or switch to feature branches as you please. No sluggish CI builds, stale - caches, wrong type hints, or memory hungry language servers that slow you - down.`)} -

-

- // ReactRouter.Link.to)}> - // - // -

- } + paragraph={React.string(`ReScript cares about a consistent and fast feedback loop for any codebase size. Refactor code, pull complex changes, or switch to feature branches as you please. That same speed also makes AI-assisted iteration much easier to validate and keep moving.`)} /> let item2 = @@ -409,12 +383,7 @@ module MainUSP = { } polygonDirection=Up - paragraph={React.string(`Every ReScript app is fully typed and provides - reliable type information for any given value in your program. We - prioritize simpler types over complex types for the sake of - clarity and easy debugability. No \`any\`, no magic types, no surprise - \`undefined\`. - `)} + paragraph={React.string(`Every ReScript app is fully typed and provides reliable type information for any given value in your program. We prioritize simpler types over complex types for the sake of clarity and easy debugability. That also makes AI-generated changes easier to review and correct.`)} /> let item3 = @@ -431,9 +400,7 @@ module MainUSP = { src="https://assets-17077.kxcdn.com/videos/interop-example-2.mp4" type_="video/mp4" /> } - paragraph={React.string(`Use any library from JavaScript, export ReScript - libraries to JavaScript, automatically generate TypeScript types. It's - like you've never left the good parts of JavaScript at all.`)} + paragraph={React.string(`Use any library from JavaScript, export ReScript libraries to JavaScript, automatically generate TypeScript types. It's like you've never left the good parts of JavaScript at all, including the SDKs and tools that power modern AI products.`)} /> @react.component @@ -446,6 +413,57 @@ module MainUSP = { } } +module AgenticWorkflows = { + type point = { + title: string, + body: string, + } + + let points = [ + { + title: "Readable code helps agents stay on track", + body: "ReScript's syntax is small, consistent, and easy to scan, which makes generated edits easier to inspect and prompts easier to ground in real code.", + }, + { + title: "Compiler errors create a tighter repair loop", + body: "Instead of vague runtime failures, agents get concrete feedback about what is wrong and where the contract broke. That makes iterative repair much more reliable.", + }, + { + title: "Humans can still review the result", + body: "ReScript compiles to straightforward JavaScript, so teams can inspect output, debug behavior, and keep handoff between human and agent work understandable.", + }, + ] + + @react.component + let make = () => { +
+
+
+

+ {React.string("Why ReScript works well with coding agents")} +

+

+ {React.string(`Coding agents tend to work best when the surrounding system is readable, predictable, and easy to review. ReScript helps by keeping the source language simple, the compiler feedback fast, and the generated output understandable.`)} +

+
+
+ {points + ->Array.mapWithIndex((point, i) => +
+

{React.string(point.title)}

+

{React.string(point.body)}

+
+ ) + ->React.array} +
+
+
+ } +} + module OtherSellingPoints = { @react.component let make = () => { @@ -467,11 +485,7 @@ module OtherSellingPoints = { {React.string(`A community of programmers who value getting things done`)}

- {React.string(`No language can be popular without a solid - community. A great type system isn't useful if library authors - abuse it. Performance doesn't show if all the libraries are slow. - Join the ReScript community — A group of companies and individuals - who deeply care about simplicity, speed and practicality.`)} + {React.string(`No language can be popular without a solid community. A great type system isn't useful if library authors abuse it. Performance doesn't show if all the libraries are slow. That pragmatic mindset matters even more when teams start using coding agents and need changes to stay understandable.`)}

// Item 3 @@ -556,6 +567,31 @@ module TrustedBy = { } } +module AgenticGuideCTA = { + @react.component + let make = () => { +
+
+
+

+ {React.string("Learn more about ReScript and coding agents")} +

+

+ {React.string(`Read a short guide on why readable source, strong types, and fast compiler feedback help when humans and coding agents work together.`)} +

+
+ + + +
+
+ } +} + module CuratedResources = { type card = { imgSrc: string, @@ -723,8 +759,10 @@ let make = (~components=MarkdownComponents.default) => { + +
diff --git a/markdown-pages/docs/manual/agentic-workflows.mdx b/markdown-pages/docs/manual/agentic-workflows.mdx new file mode 100644 index 000000000..137813f13 --- /dev/null +++ b/markdown-pages/docs/manual/agentic-workflows.mdx @@ -0,0 +1,33 @@ +--- +title: "ReScript and Coding Agents" +description: "How ReScript supports teams working with coding agents" +canonical: "/docs/manual/agentic-workflows" +section: "Guides" +order: 4 +--- + +# ReScript and Coding Agents + +ReScript is a strong fit for teams working with coding agents because it reduces ambiguity in the source language, surfaces errors early through the compiler, and keeps generated output understandable. This guide explains why those properties matter in real development workflows. + +## Readable code is easier to steer + +Agents do better when the language they are editing is small, regular, and easy to inspect. ReScript keeps the syntax compact and consistent, which makes prompts easier to ground in the actual code and makes generated changes easier for humans to review. + +## Compiler feedback tightens the repair loop + +When an agent makes an incorrect assumption, fast compiler feedback matters. ReScript turns many mistakes into concrete, local errors instead of vague runtime failures, which gives both the agent and the human reviewer a clearer path to the next fix. + +## Reviewable JavaScript keeps handoff practical + +ReScript compiles to straightforward JavaScript, so teams can still inspect output, debug behavior, and understand how a change behaves in the wider JavaScript ecosystem. That keeps the handoff between agent-written code and human review practical. + +## You can keep your existing stack + +Using ReScript does not mean walking away from the JavaScript ecosystem your product already depends on. You can keep using the SDKs, APIs, frameworks, and deployment tooling your team already knows while adding stronger guarantees where correctness and maintainability matter most. + +## Where to start + +- For setup, see [Installation](./installation.mdx). +- For adding ReScript to an existing codebase, see [Converting from JS](./converting-from-js.mdx). +- For editor and compiler feedback loops, see [Code Analysis](./editor-code-analysis.mdx). From 654736a1820c4b02d1d294983965fb587e1ea781 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Fri, 24 Apr 2026 17:59:24 -0400 Subject: [PATCH 2/5] docs: add light AI notes to manual Add a small set of measured references to coding-agent and AI-assisted workflows in the manual pages where they fit naturally. Keep the changes limited to overview, setup, migration, tooling, performance, and LLM documentation so the docs stay close to their existing tone. --- markdown-pages/docs/manual/build-performance.mdx | 2 ++ markdown-pages/docs/manual/converting-from-js.mdx | 2 ++ markdown-pages/docs/manual/editor-code-analysis.mdx | 2 ++ markdown-pages/docs/manual/installation.mdx | 4 ++++ markdown-pages/docs/manual/introduction.mdx | 4 ++++ markdown-pages/docs/manual/llms.mdx | 1 + 6 files changed, 15 insertions(+) diff --git a/markdown-pages/docs/manual/build-performance.mdx b/markdown-pages/docs/manual/build-performance.mdx index 7af0ea73a..1b0ac5154 100644 --- a/markdown-pages/docs/manual/build-performance.mdx +++ b/markdown-pages/docs/manual/build-performance.mdx @@ -70,6 +70,8 @@ ReScript doesn't take whole seconds to run every time. The bulk of the build per In short, thanks to our compiler and the build system's architecture, we're able to **only build what's needed**. If `MyFile.res` isn't changed, it isn't recompiled. Renaming or moving files is handled automatically, with no stale builds. +That kind of tight, correct incremental feedback is especially useful in coding-agent workflows, where small edits need to be validated quickly. + ## Speed Up Incremental Build ReScript uses the concept of interface files (`.resi`) (or, equivalently, [module signatures](./module.mdx#signatures)). Exposing only what you need naturally speeds up incremental builds. E.g. if you change a `.res` file whose corresponding `.resi` file doesn't expose the changed part, then you've reduced the amount of dependent files you have to rebuild. diff --git a/markdown-pages/docs/manual/converting-from-js.mdx b/markdown-pages/docs/manual/converting-from-js.mdx index 104212f38..f01b3e512 100644 --- a/markdown-pages/docs/manual/converting-from-js.mdx +++ b/markdown-pages/docs/manual/converting-from-js.mdx @@ -87,6 +87,8 @@ Open an editor tab for `src/Main.res.js`. Do a command-line `diff -u src/main.js **Always make sure** that at each step, you keep the ReScript output `.res.js` file open to compare against the existing JavaScript file. Our compilation output is very close to your hand-written JavaScript; you can simply eye the difference to catch conversion bugs! +This step-by-step workflow also pairs well with AI-assisted migrations: a tool can make a small change, and you can review the generated JS against the original file at each step. + ## Step 3: Extract Parts into Idiomatic ReScript Let's turn the `defaultId` variable into a ReScript let-binding: diff --git a/markdown-pages/docs/manual/editor-code-analysis.mdx b/markdown-pages/docs/manual/editor-code-analysis.mdx index 9a1a5bca4..3659a6056 100644 --- a/markdown-pages/docs/manual/editor-code-analysis.mdx +++ b/markdown-pages/docs/manual/editor-code-analysis.mdx @@ -19,6 +19,8 @@ Dead code refers to code that's present in your codebase but is never executed. ReScript’s language design allows for accurate and efficient dead code analysis using the **ReScript Code Analyzer**, available via the official VSCode extension. +This is useful not only for manual refactors, but also for AI-assisted edits where fast project-wide feedback helps catch incorrect assumptions early. + ### Prerequisites - ReScript VSCode extension (v1.8.2 or higher) diff --git a/markdown-pages/docs/manual/installation.mdx b/markdown-pages/docs/manual/installation.mdx index f02c9ba87..139a799f0 100644 --- a/markdown-pages/docs/manual/installation.mdx +++ b/markdown-pages/docs/manual/installation.mdx @@ -68,6 +68,8 @@ That compiles your ReScript into JavaScript, then uses Node.js to run said JavaS **When taking your first steps with ReScript, we recommend you use our unique workflow of keeping a tab open for the generated JS file** (`.res.js`/`.res.mjs`), so that you can learn how ReScript transforms into JavaScript. Not many languages output clean JavaScript code you can inspect and learn from! With our [VS Code extension](https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode), use the command "ReScript: Open the compiled JS file for this implementation file" to open the generated JS file for the currently active ReScript source file. +That workflow is also handy when experimenting with coding agents, since both the source and generated JS stay easy to inspect. + During development, instead of running `npm run res:build` each time to compile, use `npm run res:dev` to start a watcher that recompiles automatically after file changes. ## Integrate Into an Existing JS Project @@ -172,6 +174,8 @@ bun create rescript-app Since ReScript compiles to clean readable JS files, the rest of your existing toolchain (e.g. Vite, Rspack, Rollup) should just work! +That low setup overhead also makes it practical to try ReScript in fast-moving teams, including ones exploring AI-assisted workflows. + Helpful guides: - [Converting from JS](./converting-from-js.mdx). diff --git a/markdown-pages/docs/manual/introduction.mdx b/markdown-pages/docs/manual/introduction.mdx index eb5fb8993..db6ba021b 100644 --- a/markdown-pages/docs/manual/introduction.mdx +++ b/markdown-pages/docs/manual/introduction.mdx @@ -42,10 +42,14 @@ A `Hello world` ReScript program generates **20 bytes** of JS code. Additionally ReScript's build time is **one or two orders of magnitude** faster than alternatives. In its watcher mode, the build system usually finishes before you switch screen from the editor to the terminal tab (two digits of milliseconds). A fast iteration cycle reduces the need of keeping one's mental state around longer; this in turn allows one to stay in the flow longer and more often. +That same fast loop is also useful in AI-assisted workflows, where small edits need to be checked and repaired quickly. + ### Readable Output ReScript's JS output is very readable. This is especially important while learning, where users might want to understand how the code's compiled, and to audit for bugs. +It also helps when teams use coding agents but still want the generated result to stay easy to inspect and review. + This characteristic, combined with a fully-featured JS interop system, allows ReScript code to be inserted into an existing JavaScript codebase almost unnoticed. ### Preservation of Code Structure diff --git a/markdown-pages/docs/manual/llms.mdx b/markdown-pages/docs/manual/llms.mdx index 7e73b6153..f12ee81ec 100644 --- a/markdown-pages/docs/manual/llms.mdx +++ b/markdown-pages/docs/manual/llms.mdx @@ -19,6 +19,7 @@ Currently, we have the following files... ...and package-level documentation: - [/docs/react/llms](../react/llms.mdx) — the LLms documentation for ReScript React. +- For a human-oriented overview of how these properties help in coding-agent workflows, see [ReScript and Coding Agents](./agentic-workflows.mdx). ## Notes From 48666c5bc6ca38218837f0e40b526dc57e2a6449 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Fri, 24 Apr 2026 18:18:22 -0400 Subject: [PATCH 3/5] docs: refine homepage AI messaging Pull the homepage copy back toward the original messaging, reduce repeated AI mentions, and fold the coding-agents guide CTA into the dedicated agent section. --- app/routes/LandingPage.res | 74 +++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 33 deletions(-) diff --git a/app/routes/LandingPage.res b/app/routes/LandingPage.res index 248db258a..89cc192b9 100644 --- a/app/routes/LandingPage.res +++ b/app/routes/LandingPage.res @@ -88,7 +88,7 @@ export {

{React.string("Readable in. Predictable out.")}

- {React.string(`Readable source, predictable output, and fast compiler feedback are useful whether changes come from a person or a coding agent. ReScript keeps the edit-review-fix loop tight for both humans and tools.`)} + {React.string(`Readable source, predictable output, and fast compiler feedback make ReScript easier to work with. That matters while learning, debugging, reviewing changes, and iterating with coding agents.`)}

// Playground widget @@ -274,7 +274,7 @@ module QuickInstall = {

{React.string("Quick Install")}

- {React.string(`You can quickly add ReScript to an existing JavaScript codebase in minutes. That low setup overhead also makes it easy to experiment in fast-moving teams, including ones trying AI-assisted workflows.`)} + {React.string(`You can quickly add ReScript to an existing JavaScript codebase in minutes.`)}

@@ -368,7 +368,15 @@ module MainUSP = { media={} - paragraph={React.string(`ReScript cares about a consistent and fast feedback loop for any codebase size. Refactor code, pull complex changes, or switch to feature branches as you please. That same speed also makes AI-assisted iteration much easier to validate and keep moving.`)} + paragraph={<> +

+ {React.string(`ReScript cares about a consistent and fast + feedback loop for any codebase size. Refactor code, pull complex changes, + or switch to feature branches as you please. No sluggish CI builds, stale + caches, wrong type hints, or memory hungry language servers that slow you + down.`)} +

+ } /> let item2 = @@ -383,7 +391,12 @@ module MainUSP = { } polygonDirection=Up - paragraph={React.string(`Every ReScript app is fully typed and provides reliable type information for any given value in your program. We prioritize simpler types over complex types for the sake of clarity and easy debugability. That also makes AI-generated changes easier to review and correct.`)} + paragraph={React.string(`Every ReScript app is fully typed and provides + reliable type information for any given value in your program. We + prioritize simpler types over complex types for the sake of + clarity and easy debugability. No \`any\`, no magic types, no surprise + \`undefined\`. + `)} /> let item3 = @@ -400,7 +413,9 @@ module MainUSP = { src="https://assets-17077.kxcdn.com/videos/interop-example-2.mp4" type_="video/mp4" /> } - paragraph={React.string(`Use any library from JavaScript, export ReScript libraries to JavaScript, automatically generate TypeScript types. It's like you've never left the good parts of JavaScript at all, including the SDKs and tools that power modern AI products.`)} + paragraph={React.string(`Use any library from JavaScript, export ReScript + libraries to JavaScript, automatically generate TypeScript types. It's + like you've never left the good parts of JavaScript at all.`)} /> @react.component @@ -459,6 +474,18 @@ module AgenticWorkflows = { ) ->React.array}
+
+

+ {React.string(`Read a short guide on why readable source, strong types, and fast compiler feedback help when humans and coding agents work together.`)} +

+ + + +
} @@ -485,7 +512,11 @@ module OtherSellingPoints = { {React.string(`A community of programmers who value getting things done`)}

- {React.string(`No language can be popular without a solid community. A great type system isn't useful if library authors abuse it. Performance doesn't show if all the libraries are slow. That pragmatic mindset matters even more when teams start using coding agents and need changes to stay understandable.`)} + {React.string(`No language can be popular without a solid + community. A great type system isn't useful if library authors + abuse it. Performance doesn't show if all the libraries are slow. + Join the ReScript community — A group of companies and individuals + who deeply care about simplicity, speed and practicality.`)}

// Item 3 @@ -567,31 +601,6 @@ module TrustedBy = { } } -module AgenticGuideCTA = { - @react.component - let make = () => { -
-
-
-

- {React.string("Learn more about ReScript and coding agents")} -

-

- {React.string(`Read a short guide on why readable source, strong types, and fast compiler feedback help when humans and coding agents work together.`)} -

-
- - - -
-
- } -} - module CuratedResources = { type card = { imgSrc: string, @@ -762,7 +771,6 @@ let make = (~components=MarkdownComponents.default) => { -
From a2e261b06f822dbd9f31d67c51c06e22b03839d6 Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Fri, 24 Apr 2026 18:39:19 -0400 Subject: [PATCH 4/5] restore some original text --- app/routes/LandingPage.res | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/app/routes/LandingPage.res b/app/routes/LandingPage.res index 89cc192b9..529238656 100644 --- a/app/routes/LandingPage.res +++ b/app/routes/LandingPage.res @@ -257,6 +257,12 @@ module QuickInstall = { @react.component let make = () => {
+

{React.string("Quick Install")}

+
+ {React.string( + "You can quickly add ReScript to your existing JavaScript codebase via npm / yarn:", + )} +
{copyBox("npm install rescript")}
{React.string("Or generate a new project from the official template with npx:")} @@ -269,15 +275,26 @@ module QuickInstall = { @react.component let make = () => {
-
-
-
-

{React.string("Quick Install")}

-

- {React.string(`You can quickly add ReScript to an existing JavaScript codebase in minutes.`)} -

-
-
+
+ //---Textblock on the left side--- +
+

+ + {React.string(`Leverage the full power`)} + + {React.string(` of JavaScript in a robustly typed language without the fear of \`any\` types.`)} +

+
+ //spacing between columns +
+

+ {React.string(`ReScript is used to ship and maintain mission-critical products with good UI and UX.`)} +

+
From a9547904e352a5bafc4f6878eb482d691168ef3f Mon Sep 17 00:00:00 2001 From: Josh Vlk Date: Fri, 24 Apr 2026 19:00:13 -0400 Subject: [PATCH 5/5] more editing --- app/routes/LandingPage.res | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/app/routes/LandingPage.res b/app/routes/LandingPage.res index 529238656..8287eadb5 100644 --- a/app/routes/LandingPage.res +++ b/app/routes/LandingPage.res @@ -88,7 +88,7 @@ export {

{React.string("Readable in. Predictable out.")}

- {React.string(`Readable source, predictable output, and fast compiler feedback make ReScript easier to work with. That matters while learning, debugging, reviewing changes, and iterating with coding agents.`)} + {React.string(`Readable source, predictable output, and fast compiler feedback make ReScript easier to work with. Those qualities help while learning, debugging, reviewing changes, or bringing coding agents into the workflow.`)}

// Playground widget @@ -453,16 +453,16 @@ module AgenticWorkflows = { let points = [ { - title: "Readable code helps agents stay on track", - body: "ReScript's syntax is small, consistent, and easy to scan, which makes generated edits easier to inspect and prompts easier to ground in real code.", + title: "Clear code is easier to guide", + body: "ReScript's small, consistent syntax makes prompts easier to ground and generated edits easier to review.", }, { - title: "Compiler errors create a tighter repair loop", - body: "Instead of vague runtime failures, agents get concrete feedback about what is wrong and where the contract broke. That makes iterative repair much more reliable.", + title: "Compiler feedback helps close the loop", + body: "When a change breaks a contract, the compiler points to it directly. That gives both humans and tools a faster path to a correct fix.", }, { - title: "Humans can still review the result", - body: "ReScript compiles to straightforward JavaScript, so teams can inspect output, debug behavior, and keep handoff between human and agent work understandable.", + title: "The output stays readable", + body: "ReScript compiles to straightforward JavaScript, so teams can inspect behavior, debug issues, and hand work back and forth without losing the thread.", }, ] @@ -471,11 +471,9 @@ module AgenticWorkflows = {
-

- {React.string("Why ReScript works well with coding agents")} -

+

{React.string("Working with coding agents")}

- {React.string(`Coding agents tend to work best when the surrounding system is readable, predictable, and easy to review. ReScript helps by keeping the source language simple, the compiler feedback fast, and the generated output understandable.`)} + {React.string(`The same qualities that make ReScript pleasant for people also make it a good fit for coding agents: clear source, fast feedback, and JavaScript output that stays easy to inspect.`)}

@@ -495,7 +493,7 @@ module AgenticWorkflows = { className="mt-12 lg:mt-16 rounded-2xl border border-fire-10 bg-white px-6 py-6 lg:px-8 lg:py-7 flex flex-col gap-6 lg:flex-row lg:items-center lg:justify-between" >

- {React.string(`Read a short guide on why readable source, strong types, and fast compiler feedback help when humans and coding agents work together.`)} + {React.string(`Read a short guide about using ReScript alongside coding agents.`)}