Skip to content

Commit

Permalink
Use .res.js instead of .bs.js
Browse files Browse the repository at this point in the history
  • Loading branch information
fhammerschmidt committed Dec 9, 2023
1 parent 9595ce4 commit 99f280a
Show file tree
Hide file tree
Showing 4 changed files with 21 additions and 20 deletions.
19 changes: 10 additions & 9 deletions pages/docs/manual/latest/build-configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ Your source files need to be specified explicitly (we don't want to accidentally
"sources": ["src", "examples"]
}
```

```json
{
"sources": {
Expand All @@ -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"]
},
}
}
```

Expand Down Expand Up @@ -140,7 +141,8 @@ 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"`
Expand All @@ -151,16 +153,15 @@ one of the following:
- `".bs.mjs"`
- `".bs.cjs"`

Currently prefer `.bs.js` for now.
Currently prefer `.res.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.bs')`. 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 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

Expand Down
10 changes: 5 additions & 5 deletions pages/docs/manual/latest/converting-from-js.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions pages/docs/manual/latest/interop-with-js-build-systems.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.bs')`, without needing a loader.

## Use Loaders on ReScript Side

Expand Down
8 changes: 4 additions & 4 deletions pages/docs/react/latest/router.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down

0 comments on commit 99f280a

Please sign in to comment.