# recoil-nexus

> A small Typescript package to access your Recoil atoms outside of React components.

Latest version **0.5.1** (published 2024-07-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install recoil-nexus
pnpm add recoil-nexus
yarn add recoil-nexus
bun add recoil-nexus
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.1 |
| Published | 2024-07-19 |
| First published | 2020-12-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 162 |
| Author | Luis Antonio Canettoli Ordoñez |
| Maintainers | luis.antonio |
| Keywords | recoil, connection, outside, react, typescript, nexus |

## Links

- npm: https://www.npmjs.com/package/recoil-nexus
- Repository: https://github.com/luisanton-io/recoil-nexus
- Homepage: https://github.com/luisanton-io/recoil-nexus#readme
- Issues: https://github.com/luisanton-io/recoil-nexus/issues
- npm.io page: https://npm.io/package/recoil-nexus

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.5.1 (latest) — 2024-07-19
- 0.5.0 — 2023-05-29
- 0.4.0 — 2022-07-07
- 0.3.18 — 2022-06-21
- 0.3.17 — 2022-06-21
- 0.3.16 — 2022-06-21
- 0.3.15 — 2022-01-19
- 0.3.14 — 2021-12-29
- 0.3.13 — 2021-12-29
- 0.3.12 — 2021-12-29
- 0.3.11 — 2021-12-29
- 0.3.10 — 2021-12-09
- 0.3.9 — 2021-11-08
- 0.3.8 — 2021-11-04
- 0.3.7 — 2021-11-04
- … 27 more at https://npm.io/package/recoil-nexus/versions

## README

# R E C O I L - N E X U S

##### <div align="right">by [Luis Antonio Canettoli Ordoñez](http://luisanton.io)</div>

If you have been using **[recoil](https://recoiljs.org/)** for a while, you might have faced that outside React Components it's not possible to get or update values from atoms.

This Typescript implementation will workaround the issue and let you do so.

## Live Example

- [Simple Loader Example](https://codesandbox.io/s/github/luisanton-io/simple-loader-with-nexus)

## Install

**npm**

`npm i recoil-nexus`

**yarn**

`yarn add recoil-nexus`

## Usage

### 1. Add `RecoilNexus` in your `RecoilRoot`

```tsx
import React from "react";
import { RecoilRoot } from "recoil";
import RecoilNexus from "recoil-nexus";

export default function App() {
  return (
    <RecoilRoot>
      <RecoilNexus />

      {/* ... */}
    </RecoilRoot>
  );
}

export default App;
```

### 2. Use the following methods to get/set values passing your atom as a parameter.

| Method      | Returns                                                   |
| :---------- | :-------------------------------------------------------- |
| `getRecoil` | getter function |
| `getRecoilPromise` | getter function, returns a promise. To be used with asynchronous selectors. |
| `setRecoil` | setter function, pass value to be set or updater function as second parameter |
| `resetRecoil` | pass atom as parameter to reset to default value |

Read current state:
```tsx
const loading = getRecoil(loadingState);
```

Setting the new state like this is not inherently wrong: 
```tsx
setRecoil(loadingState, !loading);
```
However, if the new state depends on the previous one (like in this case), preferably use an
updater function to correctly batch React state updates, as reading and
updating the state at the same time could lead to [unexpected results](https://github.com/luisanton-io/recoil-nexus/issues/33).
```tsx
import { setRecoil } from "recoil-nexus"

export function toggleLoader() {
  setRecoil(loadingState, loading => !loading)
}
```

## Test Setup

### Jest

When testing in [Jest](https://jestjs.io), we need to set `"transformIgnorePatterns": []` in our jest config, otherwise a `SyntaxError: Cannot use import statement outside a module` will cause the tests to fail. This can be acheived one of the following ways, depending on how you are defining your jest config:

```
export default config
```
- in `jest.config.js`
```
"transformIgnorePatterns": []
```

- in the top level of the `package.json`
```
"jest": {
  "transformIgnorePatterns": []
},
```
---

### Credits

Kudos to [VeepCream](https://github.com/VeepCream)'s [recoil-outside](https://github.com/VeepCream/recoil-outside) original idea and Javascript implementation.   
In this Typescript port/enhancement, I decided to remove RxJS and rely on native Recoil promises and loadables only.

---
_Source: https://npm.io/package/recoil-nexus · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._