diff --git a/app/routes/LandingPage.res b/app/routes/LandingPage.res index b784ebf3a..68828aa7a 100644 --- a/app/routes/LandingPage.res +++ b/app/routes/LandingPage.res @@ -19,9 +19,9 @@ module Intro = { efficient JavaScript that humans and AI tools can read and understand.`)}

- {React.string(`Its fast compiler and static type system keep feedback loops tight, - so you can move quickly with AI assistance while maintaining - confidence as your codebase grows.`)} + {React.string(`Its fast compiler and static type system keep feedback loops tight for + teams using AI tools or coding agents, while maintaining confidence + as your codebase grows.`)}

@@ -385,14 +385,8 @@ module MainUSP = { 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)}> - // - // + down. The same tight loop helps developers using coding agents validate + small edits without leaving the normal build workflow.`)}

} /> @@ -446,6 +440,67 @@ module MainUSP = { } } +module AgenticWorkflows = { + type point = { + title: string, + body: string, + } + + let points = [ + { + title: "Clear code is easier to guide", + body: "ReScript's small, consistent syntax helps developers give agents grounded context and keeps generated edits easier to review.", + }, + { + title: "Compiler feedback helps close the loop", + body: "When a change breaks a contract, the compiler points to it directly. That gives developers and agents a faster path to a correct fix.", + }, + { + 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.", + }, + ] + + @react.component + let make = () => { +
+
+
+

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

+

+ {React.string(`For teams using coding agents, the same qualities that make ReScript pleasant for people also keep generated changes easier to guide and review: clear source, fast feedback, and JavaScript output that stays easy to inspect.`)} +

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

{React.string(point.title)}

+

{React.string(point.body)}

+
+ ) + ->React.array} +
+
+

+ {React.string(`Read a short guide about using ReScript alongside coding agents.`)} +

+ + + +
+
+
+ } +} + module OtherSellingPoints = { @react.component let make = () => { @@ -697,9 +752,9 @@ let make = (~components=MarkdownComponents.default) => { title="The ReScript Programming Language" description={`JavaScript Made Simple for Humans and AI. ReScript is a strongly typed language that compiles to clean, efficient JavaScript that humans and AI tools can read and understand. - Its fast compiler and static type system keep feedback loops tight, - so you can move quickly with AI assistance while maintaining - confidence as your codebase grows.`} + Its fast compiler and static type system keep feedback loops tight for + teams using AI tools or coding agents, while maintaining confidence + as your codebase grows.`} keywords=["ReScript", "rescriptlang", "JavaScript", "JS", "TypeScript"] />
@@ -723,6 +778,7 @@ 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). diff --git a/markdown-pages/docs/manual/build-performance.mdx b/markdown-pages/docs/manual/build-performance.mdx index 7af0ea73a..3f5b7599f 100644 --- a/markdown-pages/docs/manual/build-performance.mdx +++ b/markdown-pages/docs/manual/build-performance.mdx @@ -68,7 +68,7 @@ The watcher is also just a thin file watcher that calls `rescript.exe`. We don't ReScript doesn't take whole seconds to run every time. The bulk of the build performance comes from incremental build, aka re-building a previously built project when a few files changed. -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. +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 tight, correct incremental feedback helps developers using coding agents validate small edits quickly. ## Speed Up Incremental Build diff --git a/markdown-pages/docs/manual/converting-from-js.mdx b/markdown-pages/docs/manual/converting-from-js.mdx index 104212f38..fd68c90e8 100644 --- a/markdown-pages/docs/manual/converting-from-js.mdx +++ b/markdown-pages/docs/manual/converting-from-js.mdx @@ -85,7 +85,7 @@ Add this file to `rescript.json`: Open an editor tab for `src/Main.res.js`. Do a command-line `diff -u src/main.js src/Main.res.js`. Aside from whitespaces, you should see only minimal, trivial differences. You're already a third of the way done! -**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! +**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 works well for developers using agents: 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 diff --git a/markdown-pages/docs/manual/editor-code-analysis.mdx b/markdown-pages/docs/manual/editor-code-analysis.mdx index 9a1a5bca4..99b4838ae 100644 --- a/markdown-pages/docs/manual/editor-code-analysis.mdx +++ b/markdown-pages/docs/manual/editor-code-analysis.mdx @@ -17,7 +17,7 @@ Dead code refers to code that's present in your codebase but is never executed. - Confusion during development - Misleading assumptions about functionality -ReScript’s language design allows for accurate and efficient dead code analysis using the **ReScript Code Analyzer**, available via the official VSCode extension. +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 for manual refactors and for developers using agents, because fast project-wide feedback helps catch incorrect assumptions early. ### Prerequisites diff --git a/markdown-pages/docs/manual/installation.mdx b/markdown-pages/docs/manual/installation.mdx index f02c9ba87..a72d513c9 100644 --- a/markdown-pages/docs/manual/installation.mdx +++ b/markdown-pages/docs/manual/installation.mdx @@ -66,7 +66,7 @@ bun create rescript-app That compiles your ReScript into JavaScript, then uses Node.js to run said JavaScript. -**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. +**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. For developers using agents, that same workflow keeps both the source and generated JS 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. @@ -170,7 +170,7 @@ 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! +Since ReScript compiles to clean readable JS files, the rest of your existing toolchain (e.g. Vite, Rspack, Rollup) should just work, which keeps setup overhead low for fast-moving teams using AI or coding agents. Helpful guides: diff --git a/markdown-pages/docs/manual/introduction.mdx b/markdown-pages/docs/manual/introduction.mdx index eb5fb8993..8beeef4f1 100644 --- a/markdown-pages/docs/manual/introduction.mdx +++ b/markdown-pages/docs/manual/introduction.mdx @@ -40,11 +40,11 @@ A `Hello world` ReScript program generates **20 bytes** of JS code. Additionally ### Fast Iteration Loop -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. +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, including when developers using agents need to check and repair small edits 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. +ReScript's JS output is very readable. This is especially important while learning, where users might want to understand how the code's compiled, when auditing for bugs, and when teams use coding agents but still want generated changes 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. diff --git a/markdown-pages/docs/manual/llms.mdx b/markdown-pages/docs/manual/llms.mdx index 7e73b6153..a2ac6b2f4 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. +- [ReScript and Coding Agents](./agentic-workflows.mdx) — guidance for teams using coding agents with ReScript. ## Notes