aurelia / aurelia/documentation

Remove reference to, or even warn about, using immer and binding with aurelia-store

Open
#478 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
104
Forks
108
PR merge metrics
No merged PRs in 30d

Description

**I'm submitting a bug report**

* **Library Version:**
aurelia-framework 1.3.1
aurelia-store 1.6.0
immer 6.0.3

**Please tell us about your environment:**
* **Operating System:**
Windows 10

* **Node Version:**
13.12.0

* **NPM Version:**
6.14.4

* **JSPM OR Webpack AND Version**
Webpack 4.42.1

* **Browser:**
Firefox 75.0

* **Language:**
TypeScript 3.8.3

**Current behavior:**
The Aurelia documentation guide for "Managing App State" demonstrates binding state properties directly in templates. The documentation then indicates that readers should review the Immer library to assist with ensuring their state remains immutable, implying that Immer is compatible with Aurelia when used in this way.

However, actually attempting to use Immer with Aurelia while binding directly to the store state results in the error "Immer drafts cannot have computed properties". I believe this is due to data-binding modifying the state objects with getters/setters for observing the values. The error means that Immer cannot reliably clone the object because it contains functions/getters/setters/computed properties.

More information about this error can be found here:
https://github.com/immerjs/immer/issues/392
https://github.com/immerjs/immer/issues/317
Possibly https://github.com/immerjs/immer/issues/202

You can see this error in action here (Click the button after the app loads):
https://codesandbox.io/s/aurelia-javascript-sandbox-21zw1?file=/src/app.js

**Expected/desired behavior:**
I spent a few hours researching and testing aurelia-store with Immer and aurelia-store, thinking I was doing something wrong. Eventually I gave up and asked about it in discord to find out it was a known issue.

IMO the documentation needs to be updated to remove mentioning Immer, or document an alternate approach that allows the use of Immer, such as not binding to the store state directly. Though I found even that can be tricky, as if you're not careful to properly copy your component state from the store state, aurelia still manages to bind into the store state and it's very difficult to track down where this is happening.

I also acknowledge I'm fairly new to Aurelia, so if I'm doing something wrong, please let me know.

Contributor guide

Open the contributing guide

Research direction

Open the “Managing App State” guide and reproduce the behavior in the linked CodeSandbox to understand the documented Immer workflow. Update the guide to remove the Immer reference or clearly warn about its incompatibility with direct store bindings; done means the documentation no longer implies that combination is safe.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.