diff --git a/app/routes/LandingPage.res b/app/routes/LandingPage.res index b784ebf3a..8287eadb5 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 make ReScript easier to work with. Those qualities help while learning, debugging, reviewing changes, or bringing coding agents into the workflow.`)} +

+
// Playground widget
-

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

} /> @@ -446,6 +445,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 makes prompts easier to ground and 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 both humans and tools 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(`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.`)} +

+
+
+ {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 = () => { @@ -723,6 +783,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..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