You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Can I use Vite, or Next.js? Is it only for React? Can I use Node or Deno?
8
-
---
8
+
---
9
+
10
+
You've taken a look and ReScript and you want to try it out, but how do you get started? There's the [installation](https://rescript-lang.org/docs/manual/latest/installation) page in the docs,
11
+
which is great if you want to set up a new React app using [create-rescript-app](https://github.com/rescript-lang/create-rescript-app). There's instructions on how to add it to an existing project or set it up manually.
12
+
But that doesn't really answer the question "Can I use this with X?".
13
+
14
+
## You can use ReScript anywhere you can use JavaScript
15
+
ReScript is just a language that compiles to JavaScript. Unlike other language like [Elm](https://elm-lang.org/) or [PureScript](https://www.purescript.org/) ReScript doesn't have a recommended framework or independent ecosystem, it's just part of the normal JavaScript world.
16
+
17
+
Here's a really basic example that you can run in Node after compiling:
18
+
19
+
```res
20
+
// index.res
21
+
Console.log("Hello")
22
+
```
23
+
24
+
Just run `node index.res.js` and you'll see "Hello" logged to the console. You can import compiled ReScript into any project that could import JavaScript.
25
+
But real world projects aren't just JavaScript; they use libraries and frameworks. This is where [bindings](https://rescript-lang.org/docs/manual/latest/external) come into play.
26
+
A binding is a way to tell ReScript the types and imports from external JavaScript. You can think of bindings in the same way that you need to create a `*.d.ts` file to add types to a JavaScript library that doesn't use TypeScript.
27
+
28
+
ReScript has great integration with [React](https://rescript-lang.org/docs/react/latest/introduction) and those bindings are kept up to date by the core team, but that doesn't mean you don't have other options!
29
+
30
+
## Using existing bindings
31
+
While ReScript isn't as large as TypeScript it has a small but growing list of bindings you can find on NPM. The website has a [package explorer](https://rescript-lang.org/packages) you can use to find official and community maintained bindings.
32
+
Many major libraries have existing bindings. Here's a small set of what you can find.
## Using libraries and frameworks created for ReScript
47
+
Bindings are great if you want to work with libraries written with JavaScript, but there are great options for libraries and frameworks written with ReScript, which means you don't need bindings.
48
+
49
+
-[ReScript Schema](https://github.com/DZakh/rescript-schema) - The fastest parser in the entire JavaScript ecosystem with a focus on small bundle size and top-notch DX.
50
+
-[rescript-relay](https://github.com/zth/rescript-relay) - This is an amazing way to connect React to Relay and GraphQL
51
+
-[rescript-rest](https://github.com/DZakh/rescript-rest) - Fully typed RPC-like client, with no need for code generation!
52
+
-[rescript-edgedb](https://github.com/zth/rescript-edgedb) - Use EdgeDB fully type safe in ReScript. Embed EdgeQL right in your ReScript source code.
53
+
-[ResX](https://github.com/zth/res-x) - A ReScript framework for building server-driven web sites and applications.
54
+
55
+
## Creating your own bindings
56
+
At some point you will probably have to use a library that doesn't have bindings available. Asking on the [forum](https://forum.rescript-lang.org/) is a great place to start. Someone else might have bindings already in a project that they just haven't published to NPM.
57
+
You can also get help and guidance on how to write bindings for what you need. Usually you can figure out what you need from looking at a libraries official docs.
58
+
You don't need to write bindings for an entire library, or even for all of a functions arguments. Just write what you need as you go.
59
+
60
+
Let's take a look at the `format` function from [date-fns](https://date-fns.org/). We can see the [arguments in the docs](https://date-fns.org/v4.1.0/docs/format#arguments), and how it should be imported and used.
61
+
```res
62
+
// type signature
63
+
function format(
64
+
date: string | number | Date,
65
+
formatStr: string,
66
+
options?: FormatOptions
67
+
): string
68
+
69
+
// how it's imported
70
+
import { format } from "date-fns";
71
+
72
+
// how it's used
73
+
const result = format(new Date(2014, 1, 11), 'MM/dd/yyyy')
74
+
```
75
+
76
+
That's all we need to know to write bindings to use this function in ReScript.
77
+
The first thing we need to figure out is how to handle the type for what `date-fns` considers to be a `date`, which is `Date | string | number`. In ReScript things can't just be of different types like they can in JavaScript or TypeScript. There are a couple options here; you can make a function for each type such as `formatString` and `formatDate`, or you can create a [variant type](https://rescript-lang.org/docs/manual/latest/variant) to map to the possible input types.
78
+
Creating a function for each type is simpler, and it's most likely how you will use the library in your project. You probably have a standard type for Dates already. We'll also need a type for `FormatDateOptions` in case we want to pass options. We'll use [labled arguments](https://rescript-lang.org/docs/manual/latest/function#labeled-arguments) for our binding.
79
+
```res
80
+
// DateFns.res - you might want to put this in a folder called "bindings" or "external"
81
+
type formatDateOptions // we're not even going to add anything to this yet until we need something
82
+
83
+
@module("date-fns") // this is the import path for the module
84
+
external formatString: (
85
+
~date: string, // the date string
86
+
~formatStr: string, // how we want it formatted
87
+
~options: formatDateOptions=?, // =? means the argument is optional
88
+
) => string = "format" // "format" is the name of the function we are importing from the module
89
+
```
90
+
91
+
Now we can use the function!
92
+
<CodeTablabels={["ReScript", "JS Output"]}>
93
+
```res
94
+
let formattedDate = DateFns.formatString(~date="2021-09-01", ~formatStr="MMMM dd, yyyy")
95
+
```
96
+
97
+
```js
98
+
import*asDateFnsfrom"date-fns";
99
+
100
+
var formattedDate =DateFns.format("2021-09-01", "MMMM dd, yyyy");
101
+
```
102
+
</CodeTab>
103
+
104
+
If we need to use `FormatDateOptions` we can add to our type definition as needed. The first option is `firstWeekContainsDate` which can either be `1` or `4`.
105
+
Here's how we could write bindings for that.
106
+
```res
107
+
@unboxed
108
+
type firstWeekContainsDate =
109
+
| @as(1) One
110
+
| @as(4) Four
111
+
112
+
type formatDateOptions = {firstWeekContainsDate: firstWeekContainsDate}
113
+
```
114
+
115
+
And when we use it it will output either `1` or `4`.
116
+
<CodeTablabels={["ReScript", "JS Output"]}>
117
+
```res
118
+
let formattedDate = formatString(
119
+
~date="2021-09-01",
120
+
~formatStr="MMMM dd, yyyy",
121
+
~options={firstWeekContainsDate: Four},
122
+
)
123
+
```
124
+
125
+
```js
126
+
import*asDateFnsfrom"date-fns";
127
+
128
+
var formattedDate =DateFns.format("2021-09-01", "MMMM dd, yyyy", {
129
+
firstWeekContainsDate:4
130
+
});
131
+
```
132
+
</CodeTab>
133
+
134
+
You can write new bindings and extend existing types as you need.
0 commit comments