Merge pull request #759 from fhammerschmidt/installation-create-rescript-app-and-res-js

Quick setup section & .bs.js -> .res.js

Author: fhammerschmidt

pages/docs/manual/latest/build-configuration.mdx

@@ -34,6 +34,7 @@ Your source files need to be specified explicitly (we don't want to accidentally
   "sources": ["src", "examples"]
 }
 ```
+
 ```json
 {
   "sources": {
@@ -59,22 +60,22 @@ You can mark your directories as dev-only (for e.g. tests). These won't be built
 
 ```json
 {
-  "sources" : {
-    "dir" : "test",
-    "type" : "dev"
+  "sources": {
+    "dir": "test",
+    "type": "dev"
   }
 }
 ```
 
-You can also explicitly allow which modules can be seen from outside. This feature is especially useful for library authors who want to have a single entry point for their users.   
+You can also explicitly allow which modules can be seen from outside. This feature is especially useful for library authors who want to have a single entry point for their users.  
 Here, the file `src/MyMainModule.res` is exposed to outside consumers, while all other files are private.
 
 ```json
 {
   "sources": {
     "dir": "src",
     "public": ["MyMainModule"]
-  },
+  }
 }
 ```
 
@@ -140,27 +141,22 @@ This configuration only applies to you, when you develop the project. When the p
 ## suffix
 
 **Since 11.0**: The suffix can now be freely chosen. However, we still suggest you stick to the convention and use
-one of the following:  
+one of the following:
+
 - `".js`
 - `".mjs"`
 - `".cjs"`
 - `".res.js"`
 - `".res.mjs"`
 - `".res.cjs"`
-- `".bs.js"`
-- `".bs.mjs"`
-- `".bs.cjs"`
-
-Currently prefer `.bs.js` for now.
 
 ### Design Decisions
 
-Generating JS files with the `.bs.js` suffix means that, on the JS side, you can do `const myReScriptFile = require('./theFile.bs')`. The benefits:
+Generating JS files with the `.res.js` suffix means that, on the JS side, you can do `const myReScriptFile = require('./TheFile.res.js')`. The benefits:
 
 - It's immediately clear that we're dealing with a generated JS file here.
-- It avoids clashes with a potential `theFile.js` file in the same folder.
+- It avoids clashes with a potential `TheFile.js` file in the same folder.
 - It avoids the need of using a build system loader for ReScript files. This + in-source build means integrating a ReScript project into your pure JS codebase **basically doesn't touch anything in your build pipeline at all**.
-- [genType](/docs/gentype/latest/introduction) requires `bs.js` for compiled JS artifacts. If you are using `genType`, you need to use `bs.js` for now.
 
 ## uncurried
 

pages/docs/manual/latest/converting-from-js.mdx

@@ -82,9 +82,9 @@ Add this file to `rescript.json`:
   },
 ```
 
-Open an editor tab for `src/Main.bs.js`. Do a command-line `diff -u src/main.js src/Main.bs.js`. Aside from whitespaces, you should see only minimal, trivial differences. You're already a third of the way done!
+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 `.bs.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!
 
 ## Step 3: Extract Parts into Idiomatic ReScript
 
@@ -225,9 +225,9 @@ exports.queryResult = queryResult;
 
 We hurrily typed `school` as a polymorphic `'whatever` and let its type be inferred by its usage below. The inference is technically correct, but within the context of bringing it a value from JavaScript, slightly dangerous. This is just the interop trick we've shown in the [`external`](external) page.
 
-Anyway, the file passes the type checker again. Check the `.bs.js` output, diff with the original `.js`; we've now converted a file over to ReScript!
+Anyway, the file passes the type checker again. Check the `.res.js` output, diff with the original `.js`; we've now converted a file over to ReScript!
 
-Now, you can delete the original, hand-written `main.js` file, and grep the files importing `main.js` and change them to importing `Main.bs.js`.
+Now, you can delete the original, hand-written `main.js` file, and grep the files importing `main.js` and change them to importing `Main.res.js`.
 
 ## (Optional) Step 5: Cleanup
 
@@ -283,7 +283,7 @@ We've:
 - typed the payload as a record with only the `student` field
 - typed `getStudentById` as the sole method of `student`
 
-Check that the `.bs.js` output didn't change. How rigidly to type your JavaScript code is up to you; we recommend not typing them too elaborately; it's sometime an endless chase, and produces diminishing returns, especially considering that the elaborate-ness might turn off your potential teammates.
+Check that the `.res.js` output didn't change. How rigidly to type your JavaScript code is up to you; we recommend not typing them too elaborately; it's sometime an endless chase, and produces diminishing returns, especially considering that the elaborate-ness might turn off your potential teammates.
 
 ## Tips & Tricks
 

pages/docs/manual/latest/import-export.mdx

@@ -17,7 +17,7 @@ Unlike JavaScript, ReScript doesn't have or need import statements:
 let studentMessage = Student.message
 ```
 ```js
-var Student = require("./Student.bs");
+var Student = require("./Student.res.js");
 var studentMessage = Student.message
 ```
 

pages/docs/manual/latest/installation.mdx

@@ -9,40 +9,98 @@ canonical: "/docs/manual/latest/installation"
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) version >= 14
-- [npm](https://docs.npmjs.com/cli/) (which comes with Node.js) or [Yarn](https://yarnpkg.com/)
+- One of the following package managers
+  - [npm](https://docs.npmjs.com/cli/) (comes with Node.js)
+  - [yarn](https://yarnpkg.com/)
+  - [pnpm](https://pnpm.io/)
+  - [bun](https://bun.sh/)
 
 ## New Project
 
-```sh
-git clone https://github.com/rescript-lang/rescript-project-template
-cd rescript-project-template
-npm install
-npm run res:build
-node src/Demo.bs.js
-```
+The fastest and easiest way to spin up a new ReScript project is with the [create-rescript-app](https://github.com/rescript-lang/create-rescript-app) project generator. You can start it with any of the aforementioned package managers or `npx`.
 
-or use the create-rescript-app tool:
+<CodeTab labels={["npm", "npx", "yarn", "pnpm", "bun"]}>
 
+```sh example
+npm create rescript-app
+```
+```sh
+npx create-rescript-app
+```
 ```sh
-npm create rescript-app // Select basic template
-cd <your-rescript-project-name>
-npm run res:build
-node src/Demo.bs.js
+yarn create rescript-app
+```
+```sh
+pnpm create rescript-app
+```
+```sh
+bun create rescript-app
 ```
 
-That compiles your ReScript into JavaScript, then uses Node.js to run said JavaScript. **We recommend you use our unique workflow of keeping a tab open for the generated `.bs.js` file**, so that you can learn how ReScript transforms into JavaScript. Not many languages output clean JavaScript code you can inspect and learn from!
+</CodeTab>
+
+- Follow the steps of the setup.
+- Trigger a ReScript build:
+  ```sh
+  npm run res:build
+  ```
+- If you selected the basic theme, simply run it with:
+  ```sh
+  node src/Demo.res.js
+  ```
+
+That compiles your ReScript into JavaScript, then uses Node.js to run said JavaScript. **We recommend you use our unique workflow of keeping a tab open for the generated `.res.js` file**, so that you can learn how ReScript transforms into JavaScript. Not many languages output clean JavaScript code you can inspect and learn from!
 
 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
 
-If you already have a JavaScript project into which you'd like to add ReScript:
+If you already have a JavaScript project into which you'd like to add ReScript you can do that in the following ways:
+
+### Quick Setup
+
+In the root directory of your project, execute:
+<CodeTab labels={["npm", "npx", "yarn", "pnpm", "bun"]}>
+
+```sh
+npm create rescript-app
+```
+```sh
+npx create-rescript-app
+```
+```sh
+yarn create rescript-app
+```
+```sh
+pnpm create rescript-app
+```
+```sh
+bun create rescript-app
+```
+
+</CodeTab>
 
+`create-rescript-app` will tell you that a `package.json` file has been detected and ask you if it should install ReScript into your project. Just follow the steps accordingly.
+
+### Manual Setup
 - Install ReScript locally:
+  <CodeTab labels={["npm", "yarn", "pnpm", "bun"]}>
+
   ```sh
   npm install rescript
   ```
-- Create a ReScript build configuration at the root:
+  ```sh
+  yarn add rescript
+  ```
+  ```sh
+  pnpm install rescript
+  ```
+  ```sh
+  bun install rescript
+  ```
+
+  </CodeTab>
+- Create a ReScript build configuration file (called `rescript.json`) at the root:
   ```json
   {
     "name": "your-project-name",
@@ -58,7 +116,7 @@ If you already have a JavaScript project into which you'd like to add ReScript:
         "in-source": true
       }
     ],
-    "suffix": ".bs.js",
+    "suffix": ".res.js",
     "bs-dependencies": []
   }
   ```

pages/docs/manual/latest/interop-with-js-build-systems.mdx

@@ -33,14 +33,14 @@ You can make ReScript JS files look even more idiomatic through the in-source +
     "module": "commonjs", // or whatever module system your project uses
     "in-source": true
   },
-  "suffix": ".bs.js"
+  "suffix": ".res.js"
 }
 ```
 
 This will:
 
 - Generate the JS files alongside your ReScript source files.
-- Use the file extension `.bs.js`, so that you can require these files on the JS side through `require('./MyFile.bs')`, without needing a loader.
+- Use the file extension `.res.js`, so that you can require these files on the JS side through `require('./MyFile.res.js')`, without needing a loader.
 
 ## Use Loaders on ReScript Side
 

pages/docs/react/latest/router.mdx

@@ -84,10 +84,10 @@ let make = () => {
 ```
 ```js
 import * as React from "react";
-import * as User from "./User.bs.js";
-import * as RescriptReactRouter from "@rescript/react/src/RescriptReactRouter.bs.js";
-import * as Home from "./Home.bs.js";
-import * as NotFound from "./NotFound.bs.js";
+import * as User from "./User.res.js";
+import * as RescriptReactRouter from "@rescript/react/src/RescriptReactRouter.res.js";
+import * as Home from "./Home.res.js";
+import * as NotFound from "./NotFound.res.js";
 
 function App(Props) {
   var url = RescriptReactRouter.useUrl(undefined, undefined);

src/components/CodeExample.res

@@ -222,22 +222,29 @@ module Toggle = {
         })
         ->Belt.Option.getWithDefault(React.null)
 
-      let buttonDiv = switch Js.Array2.find(multiple, tab => {
+      // On a ReScript tab, always copy or open the ReScript code. Otherwise, copy the current selected code.
+      let isReScript = tab =>
         switch tab.lang {
         | Some("res") | Some("rescript") => true
         | _ => false
         }
-      }) {
+
+      let buttonDiv = switch Js.Array2.findi(multiple, (tab, index) =>
+        tab->isReScript || index === selected
+      ) {
       | Some({code: ""}) => React.null
       | Some(tab) =>
         let playgroundLinkButton =
-          <Next.Link
-            href={`/try?code=${LzString.compressToEncodedURIComponent(tab.code)}}`} target="_blank">
-            // ICON Link to PLAYGROUND
-            <Icon.ExternalLink
-              className="text-gray-30 mt-px hover:cursor-pointer hover:text-gray-60 hover:bg-gray-30 w-6 h-6 p-1 rounded transition-all duration-300 ease-in-out"
-            />
-          </Next.Link>
+          tab->isReScript
+            ? <Next.Link
+                href={`/try?code=${LzString.compressToEncodedURIComponent(tab.code)}}`}
+                target="_blank">
+                // ICON Link to PLAYGROUND
+                <Icon.ExternalLink
+                  className="text-gray-30 mt-px hover:cursor-pointer hover:text-gray-60 hover:bg-gray-30 w-6 h-6 p-1 rounded transition-all duration-300 ease-in-out"
+                />
+              </Next.Link>
+            : React.null
 
         let copyButton = <CopyButton code={tab.code} />