Would you all be interested in collaborating on docs with MobX-State-Tree?

[coolsoftwaretyler]

Hey folks!

We are working to improve the MobX-State-Tree docs this year. One major gap is that we don't have a lot of real-world use case examples.

I don't use mst-gql, but I think libraries like yours and mst-query are natural answers to "how do I use MobX-State-Tree in the real world?" since MST offers opinions about how to manage state, but not a lot about how to interface with an external data layer.

I don't mean to presumptuously ask you to do more free work on our behalf, but I'd love to bring the ecosystem together, and if we can offer a space in our docs site for you to showcase this project, I think it would also help show people how they can use GraphQL and MST together for more realistic scenarios.

We'd also be happy to collaborate in other ways if this isn't interesting. Either way, let me know! Happy to chat here, or you can find my email in my GitHub profile if you want to connect individually.

Thanks!

[beepsoft]

Hi,

I use mst-gql and therefore MST in some of my projects, although I'm never sure whether I am doing things "right", so this kind of use case based examples in the documentation would be awesome.

One issue, for example, I'm always struggling with is how much logic should I put into MST and how much to leave to components. For example, I always think of my MST store as the "backend" of the application, which handles all the business logic including querying, mutations (graphql in case of mst-gql) and local data manipulations. This way all business logic and state of the app can be tested just by testing the MST store and also, the frontend can be switched easily as it is always calls the MST "backend" as necessary. I wonder, whether this is a good practice or not.

[coolsoftwaretyler]

Hey @beepsoft - yeah, I think that's a common struggle for folks.

My opinion is that MST should be used for as much as possible. Anything that can be appropriately modeled in MST, should be. I like to lean on React as a declarative UI layer, and move all the derivations, mutations, state changes, and even some side effects through MST.

Do you have any code examples where you haven't been sure about what's right? Maybe we could start with one of those and then do some writing about it. I'm sure there are many good opinions out there, but I think writing down one way will help solicit feedback and alternatives in a concrete way.

[beepsoft]

In general every React query library, naturally, provides hooks for querying/mutations and mst-gql is no exception. This is the basic example it provides:

import React from "react"
import { observer } from "mobx-react"

import { Error, Loading, Message } from "./"
import { useQuery } from "../models/reactUtils"

export const Home = observer(() => {
  const { store, error, loading, data } = useQuery((store) =>
    store.queryMessages()
  )
  if (error) return <Error>{error.message}</Error>
  if (loading) return <Loading />
  return (
    <ul>
      {data.messages.map((message) => (
        <Message key={message.id} message={message} />
      ))}
    </ul>
  )
})

It conveniently gives you access to the MST store to execute the query, gives loading state, error and finally the data.

Now if you image implementing this as an MST action:

1. You have to deal with async (store.queryMessages()), which means you cannot use await in your action, you have to fall back to .then() or generators (with flow() you lose typings - as far as I remember)
2. You have to manage loading and error state in MST. You may use something like this:

   export const QueryState = types
     .model('QueryState', {
       isLoading: types.optional(types.boolean, false),
       error: types.maybeNull(types.string)
     })
     .actions(self => ({
       startQuery() {
         self.isLoading = false
         self.error = null
       },
       setIsLoading(flag: boolean) {
         self.isLoading = flag
       },
       setError(error: string) {
         self.error = error
       }
     }))

If you have multiple query actions then for each you need a separate QueryState.
3. Finally, you need to store the result of the query in your model somehow so that it is accessible from the react component when the query finishes.

While all this is doable and straightforward, from DX point of view this is more work than the simplicity of using useQuery and having state at the component level. On the other hand, you have all your state and logic in one (easily) testable place.

I guess for PoC or simple prototypes you would just go with useQuery while for more production targeted apps you would consider a more "MST heavy" approach.

[coolsoftwaretyler]

Hey @beepsoft - this is great! Would you want to package it up into a PR for the docs over at https://mobx-state-tree.js.org/intro/welcome? If you submit a PR with a markdown file in our docs/ directory, we can collaborate on it and get it published.

[beepsoft]

I'm wondering if anyone here has direct contact with @kitze. It would be really interesting to know how he uses MST in Sizzy. The tree looks huge:

https://twitter.com/thekitze/status/1685173949301198848

@jamonholmgren or @mweststrate, perhaps?

[jamonholmgren]

I'll ask him, good question.

[coolsoftwaretyler]

Yeah that would be awesome. I would be happy to talk to him if anyone gets in touch!

[beepsoft]

Me too. :-)

[beepsoft]

Another issue that may worth mentioning or explaining more in the docs.

If you declare the actions like this (version 1):

const M = types
  .model('MyModel', {})
  .actions(self => ({
      action1(){},
      action2(){}
  }))

... you won't get proper IDE introspection, navigation and refactoring support. For example, if you Cmd+Click on action1() to see where it is referenced, IntelliJ jumps here:

node_modules/mobx-state-tree/dist/types/complex-types/model.d.ts

export interface ModelActions {
    [key: string]: FunctionWithFlag;
}

You can also use this (version 2):

const M = types
  .model('MyModel', {})
  .actions(self => {
    function action1(){}
    function action2(){}
    
    return {
      action1,
      action2
    }
  })

This is the worst: Cmd+Click jumps in to the return{} and if you Cmd+Click inside return{} it jumps to the function definition no the usages.

And finally, you can assign the actions to a named variable, which you return (version 3):

const M = types
  .model('MyModel', {})
  .actions(self => {
      const actions = {
          action1(){},
          action2(){}
      }
      return actions
  })

In this case Cmd+Click on actions1() will correctly list or jump to its usages and can refactor.

This is a huge difference in DX!.

Version 1 and 2 are the default suggestions in the docs now: https://mobx-state-tree.js.org/concepts/actions

Version 3 is mentioned as a tip: https://mobx-state-tree.js.org/tips/typescript, however, it comes with a note in bold:

NOTE: the last approach will incur runtime performance penalty as accessing such computed values (e.g. inside render() method of an observed component) always leads to full recompute (see this issue for details). For a heavily used computed properties it's recommended to use one of above approaches.

I guess this only refers to views, but should be OK for actions and volatile.

[coolsoftwaretyler]

Yeah, this is something that really gets people confused all the time (myself included). It's also not easy to discover this. When I was starting with MST I was never able to get to that doc after I found it. Also looks like it needs a big update (we're on TS 5.3.3 now, haha).

I'd be happy to accept a PR to change it, or we can just pull this comment into an issue in the MST repository.

[beepsoft]

I'm now sure how you want to organize the docs, so for now an issue would be good, I think, so that we don't forget it.

Should I copy this into a new issue in MST or create an issue and just link this discussion?

[coolsoftwaretyler]

Let's copy this into a new issue. There are a few different threads in this discussion and I think it will help us focus to narrow down to just this thread content in the new issue. Thanks!