Skip to content

Commit d388789

Browse files
MoOxMoOx
committed
website: add usage doc
1 parent 93bc395 commit d388789

3 files changed

Lines changed: 181 additions & 100 deletions

File tree

‎react-native-template-reason/README.md‎

Lines changed: 4 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -11,105 +11,14 @@ experience.
1111

1212
```console
1313
react-native init MyApp --template reason
14+
cd MyApp
1415
```
1516

16-
### Command line
17-
18-
Install BuckleScript with the following command:
17+
Add the required BuckleScript platform `bs-platform` with the following command:
1918

2019
```sh
2120
yarn add bs-platform --dev
2221
```
2322

24-
### IDE
25-
26-
To get the best development experience possible, we recommend you to use
27-
[VSCode](https://code.visualstudio.com) with
28-
[Reason Language Server](https://marketplace.visualstudio.com/items?itemName=jaredly.reason-vscode)
29-
extension & optionally
30-
[Flow Language Server](https://marketplace.visualstudio.com/items?itemName=flowtype.flow-for-vscode)
31-
extension if you have JavaScript covered by Flow.
32-
33-
If you won't want to use VSCode, at least
34-
[get a ReasonML editor plugin](https://reasonml.github.io/docs/en/editor-plugins/).
35-
36-
### `package.json`
37-
38-
To get started, add the following scripts to your `package.json`:
39-
40-
```json
41-
"scripts": {
42-
"re:watch": "bsb -clean-world -make-world -w",
43-
"re:build": "bsb -clean-world -make-world",
44-
"start": "node node_modules/react-native/local-cli/cli.js start",
45-
"start:ios": "react-native run-ios",
46-
"start:android": "react-native run-android",
47-
}
48-
```
49-
50-
Note: you probably have `start` already.
51-
52-
### Development workflow
53-
54-
_Note: `yarn` can be replaced by `npm run` in all commands below._
55-
56-
Depending on your editor &
57-
[its ReasonML integration](https://reasonml.github.io/docs/en/editor-plugins/)
58-
you might need to use:
59-
60-
```console
61-
yarn re:watch
62-
```
63-
64-
**Reminder: this step might be unecessary if your editor can handle ReasonML
65-
compilation by its own.**
66-
[Read more](https://github.com/jaredly/reason-language-server#installation).
67-
68-
As soon as `.re` files are being compiled to `.bs.js`, you can either start the
69-
project on _iOS Simulator_ (included in _Xcode_) or an Android Emulator (if you
70-
are unfamiliar with _Android Studio_, you might be interested by
71-
[Genymotion](https://www.genymotion.com)).
72-
73-
```console
74-
yarn start:ios
75-
```
76-
77-
or
78-
79-
```console
80-
yarn start:android
81-
```
82-
83-
This commands should open up a virtual device & start React Native
84-
[metro bundler](https://github.com/facebook/metro). This packager will serves
85-
the compiled Reason code to the React Native client.
86-
87-
Now you can start coding by editing files in `src/`!
88-
89-
[Read more about starting the project in your environment of choice](http://facebook.github.io/react-native/docs/getting-started).
90-
91-
**Note: as soon as you have the app installed in a simulator/emulator, you could
92-
just run**
93-
94-
```console
95-
yarn start
96-
```
97-
98-
This avoid rebuilding the entire native parts & will just start React Native
99-
metro bundler.
100-
101-
## Breakdown of existing files
102-
103-
The `react-native init` command generates a lot of boilerplate with files that
104-
might be not needed for your particular use case. Below is a breakdown of all
105-
top-level files to help you decide:
106-
107-
- `.babelrc` - required, for transpiling Javascript files to supported by the
108-
mobile engine Javascript version
109-
- `.buckconfig` - optional, configuration files for `Buck`. Can be safely
110-
removed in most cases unless you are planning on using it
111-
- `.flowconfig` - optional, used to configure `Flow`, which is a type checker
112-
for Javascript. Can be removed as you are writing our code in Reason
113-
- `.watchmanconfig` - optional, configuration for `Watchman`, which is a
114-
Facebook tool for listening to file system changes. This file is not needed,
115-
unless you plan on extending its configuration
23+
Now that you are ready to go, you can check our documentation on
24+
[how to use Reason React Native](https://reasonml-community.github.io/reason-react-native/en/docs/usage/).

‎website/docs/install.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,21 @@ React Native allows to create new project from a template, so we made one. By
2828
choosing this option you will get an hello world project that will already have
2929
all the requirements included.
3030

31+
When you have correctly
32+
[`react-native-cli`](http://facebook.github.io/react-native/docs/getting-started#the-react-native-cli)
33+
installed, you can run the following command:
34+
3135
```console
3236
react-native init MyApp --template reason
3337
```
3438

39+
Final step, you need add BuckleScript (that include ReasonML toolchain):
40+
41+
```console
42+
cd MyApp
43+
yarn add bs-platform --dev
44+
```
45+
3546
💖 Now that you project is setup, you can just check
3647
[how to use _Reason React Native_](/reason-react-native/en/docs/usage/) right
3748
away!

‎website/docs/usage.md‎

Lines changed: 166 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,173 @@ id: usage
33
title: Usage
44
---
55

6-
## Using Reason React Native
6+
When `reason-react-native`, `reason-react` and `bs-platform` are installed, you
7+
can run the following command
78

8-
@todo move here
9-
[what's in the template readme](https://github.com/reasonml-community/reason-react-native/tree/master/react-native-template-reason#readme)
9+
```console
10+
yarn bsb -make-world
11+
```
12+
13+
⚠️ _If this process looks fast to you, don't be surprised, that's because
14+
ReasonML & BuckleScript are fast!_
15+
16+
This command should compile all `.re` files to their `.bs.js` counterparts.
17+
18+
This means if you have an `src/App.re` file, you should now have `src/App.bs.js`
19+
file too.
20+
21+
You may also notice some compilation artifacts:
22+
23+
- `.bsb.lock`
24+
- `.merlin`
25+
- `lib/bs`
26+
27+
You may want to gitignore all of theses:
28+
29+
```gitignore
30+
*.bs.js
31+
.bsb.lock
32+
.merlin
33+
lib/bs
34+
```
35+
36+
_If you used our template, it should be done already_.
37+
38+
## Automate compilation of `*.re` files
39+
40+
You have multipes way to not have to think about compilation for your daily
41+
workflow
42+
43+
## Compile ReasonML files via IDE
44+
45+
To get the best development experience possible, we recommend you to use
46+
[VSCode](https://code.visualstudio.com) with
47+
[Reason Language Server](https://marketplace.visualstudio.com/items?itemName=jaredly.reason-vscode)
48+
extension. Optionally you can add
49+
[Flow Language Server](https://marketplace.visualstudio.com/items?itemName=flowtype.flow-for-vscode)
50+
extension if you have existing JavaScript covered by Flow.
51+
52+
⚠️ If you won't want to use VSCode, we still recommend you to
53+
[get a ReasonML editor plugin](https://reasonml.github.io/docs/en/editor-plugins/).
54+
55+
By having an IDE that handle ReasonML compilation, you will not have to run a
56+
command in the terminal to handle this & will just have to follow the standard
57+
React Native workflow, your ReasonML files being compiled to JavaScript.
58+
59+
You will also have inline errors & much more feature that won't be provided by
60+
using a CLI workflow.
61+
62+
## Vscode workflow
63+
64+
When you open VSCode with the Reason Language Server plugin (RLS), you won't
65+
have to do anything. The plugin will detect `bs-platform` & will handle the
66+
compilation/watching process for you.
67+
68+
In case you are facing something weird, you can always trigger a cleanup by
69+
doing `Cmd + Shift + P` and look for `Restart Reason Language Server`.
70+
71+
⛑ _Even if you decide to use Vscode or a smiliar IDE to ease your day to day
72+
development workflow, you should have a look to CLI workflow so you how it
73+
works._
74+
75+
### Compile ReasonML files via CLI
76+
77+
When you use React Native, you usually always have a terminal opened around with
78+
Metro Bundler running, which bundle the JavaScript files.
79+
80+
Now you need to also have a process watching for your ReasonML files to compile
81+
then to JavaScript. The easiest way is to rely on BuckleScript `bsb` watch
82+
option `-w`:
83+
84+
```console
85+
yarn bsb -make-world -w
86+
```
87+
88+
If you are not familiar with BuckleScript `bsb` you should know that you might
89+
sometimes have weird compilation errors due to outdated build artifacts. This
90+
should not happen often but in case you are facing something weird, you can try
91+
using `bsb` `-clean-world` option
92+
93+
```console
94+
yarn bsb -clean-world
95+
```
96+
97+
On a daily basis, you can use this complete command that will clean, build &
98+
watch for changes
99+
100+
```console
101+
yarn bsb -clean-world -make-world -w
102+
```
103+
104+
You might want to add this two commands in your `package.json` scripts:
105+
106+
```json
107+
"scripts": {
108+
"re:build": "bsb -clean-world -make-world",
109+
"re:watch": "bsb -clean-world -make-world -w",
110+
"start": "node node_modules/react-native/local-cli/cli.js start",
111+
"start:ios": "react-native run-ios",
112+
"start:android": "react-native run-android",
113+
}
114+
```
115+
116+
_Note: you probably have `start` already._
117+
118+
If you are doing this change in your scripts, you can now use this development
119+
workflow
120+
121+
#### CLI Development workflow
122+
123+
**In one terminal:**
124+
125+
```console
126+
yarn re:watch
127+
```
128+
129+
As soon as `.re` files are being compiled to `.bs.js`, you can either start the
130+
project on _iOS Simulator_ (included in _Xcode_) or an Android Emulator (if you
131+
are unfamiliar with _Android Studio_, you might be interested by
132+
[Genymotion](https://www.genymotion.com)).
133+
134+
**In another terminal:**
135+
136+
```console
137+
yarn start:ios
138+
```
139+
140+
or
141+
142+
```console
143+
yarn start:android
144+
```
145+
146+
This commands should open up a virtual device & start React Native
147+
[metro bundler](https://github.com/facebook/metro). This packager will serves
148+
the compiled Reason code to the React Native client.
149+
150+
Now you can start coding by editing files in `src/`!
151+
152+
[Read more about starting the project in your environment of choice](http://facebook.github.io/react-native/docs/getting-started).
153+
154+
**Note: as soon as you have the app installed in a simulator/emulator, you can
155+
just run**
156+
157+
```console
158+
yarn start
159+
```
160+
161+
This avoid rebuilding the entire native parts & will just start React Native
162+
metro bundler.
163+
164+
---
165+
166+
## Interoperability with JavaScript
10167

11168
### Using JavaScript components from Reason
12169

13-
@todo check out
170+
@todo
171+
172+
Meanwhile, check out
14173
[Reason React interop page](https://reasonml.github.io/reason-react/docs/en/components#interop).
15174

16175
You can also browse the source of
@@ -19,7 +178,9 @@ because that's exactly what this project is doing!
19178

20179
### Using Reason React Native components from JavaScript
21180

22-
@todo Meanwhile, check out
181+
@todo
182+
183+
Meanwhile, check out
23184
[Reason React interop page](https://reasonml.github.io/reason-react/docs/en/components#interop)
24185

25186
---

0 commit comments

Comments
 (0)