Typescript Docs and Context Providers - Confusing docs make for frustrating learning

[mix3d]

Hi, I'm new to Solid and am working on a personal site. I wanted to record a recent sour learning experience, as the docs are confusing and either incomplete or suggesting potentially bad practices.

Starting with the normal Context documentation / examples, it's pretty simple to get a context provider up and running. However, when you start adding Typescript, things get complicated.

First, you're suggested to use a factoryFunction to generate the expected Context type. This is fine, and easy to follow. The problem is when you get to the bottom of the TS suggestions, where it warns about the possibility of the context being undefined.

useCountNameContext has type () => CountNameContextType | undefined.
If you want to avoid the undefined possibility, you could assert that the context is always provided when used:
export const useCountNameContext = () => useContext(CountNameContext)!;
This is a dangerous assumption; it would be safer to actually provide a default argument to createContext so that the context is always defined. (emphasis added)

Here's my thought process:

1. Ok, it suggests using a default. No examples though. How do defaults work? (Read regular docs)
2. Ok, just pass something into the createContext function. I have this factory function already, let me just plug that in. export const CountNameContext = createContext(makeCountNameContext());
3. Typescript seems to like it, but now the Context.Provider is requiring a value be passed. It already has a default. Remove the value. Error! Why do I need a value if it has default already? Ok, let's try <CounterContext.Provider value={CounterContext.defaultValue}>
4. Get an error: "Uncaught TypeError: Comp is not a function" uhhh... ok?
5. Ask in Discord what's up, what I'm missing, etc.
6. Be told that defaults are weird and no one uses them.

• "I don't read or make the docs".
• "Docs are being rewritten".
• One suggestion is to throw an error when the context is undefined. (Reasonable suggestion)
• Other weird TS workaround suggestions.

As a new user I'm just trying to follow the instructions, but they're incomplete, and a rational extrapolation of JS docs and TS suggestions led me down the wrong path.

Now I have all these other questions that are not answered by the current docs.

• If the behavior of the default state is weird, what is weird about it? Why suggest it in the docs? What oddities do I need to be aware of?
• Why is there a risk of the Context being undefined in the first place?
  • I was told "it's because of HMR", but that doesn't explain anything.
  • If there's a default state, wouldn't the default cover the HMR issue?
  • Confused because we're setting the context right there in the provider, which is the root of the app in index.tsx, as per the example. How on earth could it be undefined even without a default?

I'm guessing that the reactivity has to be instantiated inside of a Component, hence the Provider wrapper. But that's not obvious, and if theres an option for a default value, it makes sense why I'm wondering I'm being forced to create a new value for the context. This alone is a little confusing.

This has somewhat soured an otherwise pleasant foray into learning a new framework. It was suggested I document my experience so that documentation and/or the project itself could be improved, so that's why this is here.

Thanks!