Skip to content

New readme #508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 25, 2022
Merged

New readme #508

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
58c3269
new readme
aspeddro Jul 22, 2022
6173d5f
fix license url
aspeddro Jul 22, 2022
7086e83
update readme
aspeddro Jul 24, 2022
7a5c587
sync with master
aspeddro Jul 24, 2022
b9f1859
Merge branch 'master' into new-readme
aspeddro Jul 25, 2022
6dbc8fe
sync with master
aspeddro Jul 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 115 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,44 @@
# rescript-vscode

The official VSCode plugin for ReScript.

![Screen shot](https://user-images.githubusercontent.com/1909539/101266821-790b1400-3707-11eb-8e9f-fb7e36e660e6.gif)

## Prerequisite

You **must** have `rescript >=9.1` installed locally in your project, through the usual [npm installation](https://rescript-lang.org/docs/manual/latest/installation#integrate-into-existing-js-project). Older versions are not guaranteed to work.

## Recommendation
<h1 align="center">
<a href="https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode">ReScript VSCode</a>
</h1>

<p align="center">The Official VSCode plugin for ReScript</p>

<p align="center">
<a href="https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode">
<img src="https://vsmarketplacebadge.apphb.com/version/chenglou92.rescript-vscode.svg"/>
<img src="https://vsmarketplacebadge.apphb.com/installs/chenglou92.rescript-vscode.svg"/>
</a>
</p>

<p align="center">
<img src="https://user-images.githubusercontent.com/1909539/101266821-790b1400-3707-11eb-8e9f-fb7e36e660e6.gif"/>
</p>

## Contents

- [📝 Prerequisite](#-prerequisite)
- [🌈 Supported Themes](#-supported-themes)
- [💡 Features](#-features)
- [📥 Installation](#-installation)
- [📦 Commands](#-commands)
- [🔨 Settings](#-settings)
- [🚀 Code Analyzer](#-code-analyzer)
- [Configuring the Code Analyzer](#configuring-the-code-analyzer)
- [Usage](#usage)
- [Caveats](#caveats)
- [🪄 Tips & Tricks](#-tips--tricks)
- [Hide generated files](#hide-generated-files)
- [⌨️ Use with Other Editors](#️-use-with-other-editors)
- [📰 Changelog](#-changelog)
- [👏 How to Contribute](#-how-to-contribute)
- [📄 License](#-license)

## 📝 Prerequisite

You **must** have [ReScript](https://www.npmjs.com/package/rescript) >= 9.1 installed locally in your project, through the usual [npm or yarn installation](https://rescript-lang.org/docs/manual/latest/installation#integrate-into-existing-js-project). Older versions are not guaranteed to work.

## 🌈 Supported Themes

Our highlighting works well with most popular VSCode themes, such as:

Expand All @@ -22,15 +52,10 @@ The only 2 themes we don't (and can't) support, due to their lack of coloring, a

- Dark (Visual Studio), Light (Visual Studio)

If your custom theme doesn't seem to highlight much (e.g. no colors for upper-case JSX tag, no distinction between module and variant), try one of the recommended themes to see if that's the problem. For more info, see [this post](https://github.com/rescript-lang/rescript-vscode/pull/8#issuecomment-764469070).

## Installation
> **Note**
> If your custom theme doesn't seem to highlight much (e.g. no colors for upper-case JSX tag, no distinction between module and variant), try one of the recommended themes to see if that's the problem. For more info, see [this post](https://github.com/rescript-lang/rescript-vscode/pull/8#issuecomment-764469070).

The plugin's on [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=chenglou92.rescript-vscode). In VSCode, `cmd-shift-p` -> "Install Extensions", then find "rescript-vscode".

The plugin activates on `.res` and `.resi` files. If you've already got Reason-Language-Server installed, it's possible that the latter took precedence over this one. Make sure you're using this plugin ("ReScript syntax") rather than Reason-Language-Server ("BuckleScript syntax").

## Features
## 💡 Features

- Supports `.res`, `.resi` and `bsconfig.json`.
- Syntax highlighting.
Expand All @@ -44,105 +69,110 @@ The plugin activates on `.res` and `.resi` files. If you've already got Reason-L
- Autocomplete.
- Find references.
- Rename.
- Inlay Hints
- Snippets to ease a few syntaxes:
- `external` features such as `@bs.module` and `@bs.val`
- `try`, `for`, etc.
- Folding, and [custom folding](https://code.visualstudio.com/docs/editor/codebasics#_folding) through `//#region` and `//#endregion`.

### Commands

#### `> ReScript: Create an interface file for this implementation file.`

Creates an interface file (`.resi`) for the current `.res` file, automatically filling in all types and values in the current file.

#### `> Open the compiled JS file for this implementation file.`

Opens the compiled JS file for the current ReScript file.
## 📥 Installation

#### `> ReScript: Switch implementation/interface`
Launch VS Code Quick Open (`Ctrl+P`), paste the following command, and press enter.

Switches between the implementation and interface file. If you're in a `.res` file, the command will open the corresponding `.resi` file (if it exists), and if you're in a `.resi` file the command will open the corresponding `.res` file.

> This can also be triggered with the keybinding `Alt+O`.

### Code Analyzer

The Code Analyzer is a mode in the extension that runs additional code analysis in your project. The analysis helps you find dead code at a granular level, find unhandled exceptions, and more.
```
ext install chenglou92.rescript-vscode
```

> The Code Analyzer uses [reanalyze](https://github.com/rescript-association/reanalyze), which is embedded in the extension, so you don't need to install anything extra to run it.
The plugin activates on `.res` and `.resi` files. If you've already got Reason-Language-Server installed, it's possible that the latter took precedence over this one. Make sure you're using this plugin ("ReScript syntax") rather than Reason-Language-Server ("BuckleScript syntax").

#### Configuring the Code Analyzer
## 📦 Commands

You'll need to configure what code analysis you want to run, and what (if any) directories you want to ignore. Configuration is done via adding `reanalyze` in `bsconfig.json`. You'll get autocomplete for what configuration options are valid. You can also read [all about configuring `reanalyze` here](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson).
| Command | Description |
|------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ReScript: Create an interface file for this implementation file | Creates an interface file (`.resi`) for the current `.res` file, automatically filling in all types and values in the current file. |
| ReScript: Open the compiled JS file for this implementation file | Opens the compiled JS file for the current ReScript file. |
| ReScript: Switch implementation/interface | Switches between the implementation and interface file. If you're in a `.res` file, the command will open the corresponding `.resi` file (if it exists), and if you're in a `.resi` file the command will open the corresponding `.res` file. This can also be triggered with the keybinding `Alt+O`. |
| ReScript: Start Code Analyzer | This will start code analysis in the ReScript project of the file you run the command from. |

##### Autostarting the Code Analyzer
## 🔨 Settings

The Code Analyzer needs to be started manually by default. However, you can configure the extension to start the Code Analyzer automatically via the setting `rescript.settings.autoRunCodeAnalysis`.
You'll find all ReScript specific settings under the scope `rescript.settings`.

#### Usage
| Setting | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Prompt to Start Build | If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`. |
| ReScript Binary Path | The extension will look for the existence of a `/node_modules/.bin/rescript` file and use its directory as the `binaryPath`. If it does not find it at the project root (which is where the nearest `bsconfig.json` resides), it goes up folders in the filesystem recursively until it either finds it (often the case in monorepos) or hits the top level. To override this lookup process, the path can be configured explicitly using the setting `rescript.settings.binaryPath` |
| Inlay Hints (experimental) | This allows an editor to place annotations inline with text to display type hints. Enable using `rescript.settings.inlayHints.enable: true` |
| Code Lens (experimental) | This tells the editor to add code lenses to function definitions, showing its full type above the definition. Enable using `rescript.settings.codeLens: true` |
| Autostarting the Code Analyzer | The Code Analyzer needs to be started manually by default. However, you can configure the extension to start the Code Analyzer automatically via the setting `rescript.settings.autoRunCodeAnalysis`. |

Open the command palette and run `> ReScript: Start Code Analyzer`. This will start code analysis in the ReScript project of the file you run the command from.
**Default settings:**

Dead code is highlighted in the editor, and code actions for suppressing dead code warnings are available in most cases.
```jsonc
// Whether you want the extension to prompt for autostarting a ReScript build if a project is opened with no build running
"rescript.settings.askToStartBuild": true,

When done, stop the code analysis mode by clicking the `Stop Code Analyzer` button in the editor status bar. This will clear all reported analysis warnings.
// Automatically start ReScript's code analysis.
"rescript.settings.autoRunCodeAnalysis": false,

#### Caveats
// Path to the directory where ReScript binaries are. You can use it if you haven't or don't want to use the installed ReScript from node_modules in your project.
"rescript.settings.binaryPath": null

Currently does not work for full monorepo dead code analysis (although it should work for each monorepo package individually).
// Enable (experimental) inlay hints.
"rescript.settings.inlayHints.enable": true

## Configuration
// Maximum length of character for inlay hints. Set to null to have an unlimited length. Inlay hints that exceed the maximum length will not be shown
"rescript.settings.inlayHints.maxLength": 25

You'll find all ReScript specific settings under the scope `rescript.settings`. Open your VSCode settings and type `rescript.settings` to see them.
// Enable (experimental) code lens for function definitions.
"rescript.settings.codeLens": true
```

### Autostarting ReScript builds
## 🚀 Code Analyzer

If there's no ReScript build running already in the opened project, the extension will prompt you and ask if you want to start a build automatically. You can turn off this automatic prompt via the setting `rescript.settings.askToStartBuild`.
The Code Analyzer is a mode in the extension that runs additional code analysis in your project. The analysis helps you find dead code at a granular level, find unhandled exceptions, and more.

#### How does it find my ReScript binary?
> The Code Analyzer uses [reanalyze](https://github.com/rescript-association/reanalyze), which is embedded in the extension, so you don't need to install anything extra to run it.

The extension will look for the existence of a `/node_modules/.bin/rescript` file and use its directory as the `binaryPath`. If it does not find it at the project root (which is where the nearest `bsconfig.json` resides), it goes up folders in the filesystem recursively until it either finds it (often the case in monorepos) or hits the top level.
### Configuring the Code Analyzer

To override this lookup process, the path can be configured explicitly using the setting `rescript.settings.binaryPath`.
You'll need to configure what code analysis you want to run, and what (if any) directories you want to ignore. Configuration is done via adding `reanalyze` in `bsconfig.json`. You'll get autocomplete for what configuration options are valid. You can also read [all about configuring `reanalyze` here](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson).

### Inlay Hints (experimental)
### Usage

This allows an editor to place annotations inline with text to display type hints.
Open the command palette and run `ReScript: Start Code Analyzer`. This will start code analysis in the ReScript project of the file you run the command from.

```jsonc
// Enable (experimental) inlay hints.
rescript.settings.inlayHints.enable: true
Dead code is highlighted in the editor, and code actions for suppressing dead code warnings are available in most cases.

// Maximum length of character for inlay hints. Set to null to have an unlimited length. Inlay hints that exceed the maximum length will not be shown
rescript.settings.inlayHints.maxLength: 25
```
When done, stop the code analysis mode by clicking the `Stop Code Analyzer` button in the editor status bar. This will clear all reported analysis warnings.

### Code Lens (experimental)
### Caveats

This tells the editor to add code lenses to function definitions, showing its full type above the definition.
Currently does not work for full monorepo dead code analysis (although it should work for each monorepo package individually).

```jsonc
// Enable (experimental) code lens.
rescript.settings.codeLens: true
```
## 🪄 Tips & Tricks

### Hide generated files

You can configure VSCode to collapse the JavaScript files ReScript generates under its source ReScript file. This will "hide" the generated files in the VSCode file explorer, but still leaving them accessible by expanding the source ReScript file they belong to.

Open your VSCode settings and type `editor.filenesting`. Enable the feature and scroll down to patterns.
Open your VSCode settings and type:

The example has two patterns added:

![Shows configuration of file nesting patterns in VSCode.](https://user-images.githubusercontent.com/1457626/168123605-43ef53cf-f371-4f38-b488-d3cd081879de.png)
```jsonc
"explorer.fileNesting.enabled": true,
"explorer.fileNesting.patterns": {
"*.res": "${capture}.mjs, ${capture}.js, ${capture}.cmi, ${capture}.cmt, ${capture}.cmj",
"*.resi": "${capture}.res"
},
```

This nests implementations under interfaces if they're present and nests all generated files under the main ReScript file. Adapt and tweak to your liking.

A screenshot of the result:

![Shows the end result in VSCode, with ReScript related files nested under eachother appropriately.](https://user-images.githubusercontent.com/1457626/168123647-400e2f09-31e3-45a2-b74b-190c7c207446.png)

## Use with Other Editors
## ⌨️ Use with Other Editors

This repo also contains a language server that can power other editors. **However, the language server in this project is a pure implementation detail. We don't guarantee its stability for other editors' consumption** apart from Vim and Sublime Text.

Expand All @@ -151,3 +181,15 @@ Still, if you'd like to use this language-server with other editors:
- Get the release binaries from the Github Releases page.
- Unzip the `.vsix` and get the `server` folder. That's the only folder you need.
- The language server will be at `server/out/server.js`. Call it through node, and optionally pass `--stdio` if your editor doesn't support the default JSONRPC.

## 📰 Changelog

See [CHANGELOG](CHANGELOG.md)

## 👏 How to Contribute

Read our [Contributing Guide](CONTRIBUTING.md)

## 📄 License

See the [LICENSE](./LICENSE.txt) file for details.