This is a response to a chap on twitter asking about possible improvements to prevent having to 'treasure hunt' knowledge to make React-Native work.
I am primarily a full stack web guy, with some hardware and app experience from overseeing "Zombies, Run". What did and didn't work for me may not be applicable to others!
The official docs are brief and have a number of shortcomings that required me to fill in gaps in knowledge, either via experimentation or through trawling internet forums.
One powerful but opaque component I've been using is the PanResponder. It's great! But also very thinly documented in some ways. There is one example given, but given the huge range of complexity that class could undergo, basics of understanding are often skipped over. For example, from the documentation I'm not sure what's inside the created pan responder, or how to access properties to bind to external needs such as dynamic styles.
onPanResponderGrant: (event, gestureState) => {
this.state.pan.setOffset({
x: this.state.pan.x._value,
y: this.state.pan.y._value,
});
this.state.pan.setValue({x: 0, y: 0});
},
The above is an example of a piece of code I use. It's cool to know that the offset can apparently be set. I have no idea why we're using underscore properties to access x and y. It was in someone else's codebase, and It Worked, so now it's in mine. Not an ideal transaction!
Style is the first place where we encounter unitless things given to height, margins etc. In web development, units are given to distinguish between px, em, rem, %, vh, wh, and others. By default, the assumption would be to think these are pixels, but I have no idea if that's true, and makes it difficult to not worry about certain elements being mis-sized on very small and large devices.
Unit ambiguity also extends elsewhere. Picking on poor PanResponder again, there is a vx and a vy component of gesture state, to tell you the current velocity of the gesture. Cool! However, I have no idea what's slow, what's fast, and if it's consistent across devices. From playing around, it seems to be something that's roughly between ±5, depending on direction and speed. 3 is a 'pretty vigorous swipe'. However I had to suss this out experimentally!
Debugging is a huge portion of all software engineering, and occasionally something will go wrong that's hard to catch. I put a property of dz in an object that expected a dx, and the app will simply crash.
Now I know there's very cool hardware debugging tool where you can debug in chrome and pause on caught exceptions, which is great! However I don't think it's mentioned anywhere, or at least not obviously. On the suggested iOS simulator, it is also a bit of a clandestine thing to find. Simulator -> Hardware -> Shake Gesture.
One might naively think they can just rock out any CSS3 mcguffin and expect it to work in React-Native, which is not true. However what does and doesn't work, and how to achieve interactions and aesthetics that I was used to was not very easy to figure out through the documentation.
Current React-Native guides you to writing your code in the lovely newer JS syntaxes, which is then subsequently handled by Babel. Most examples in the documentation is written in the older syntax. If you have some React experience, it's trivial to convert these, but it always instils doubt about how current the docs are.
A number of small projects are given, but a larger project would be great as it would tackle a lot of the more complex cases that are harder to extrapolate. How do you store data between sessions? How can you make animations respond to movement? How should one structure their app when they've moved beyond one JS file and no assets?
A heavy focus on commenting that provides context would of course be great!
A couple of blogs posted examples of HTML/CSS/JS functionality that I wanted to achieve with React-Native. They wrote out the code in the manner I found easier to grok, then figured out how to write the React-Native equivalent. I would have found this extremely useful a few days back to get the basic layout and style effects going.
I realise the tech is still evolving fast, but more detail on classes and a higher level context on how to compose these things together could be great. A shaky understanding of the core purpose of each component and how these interact lead to slow and, in my case, often incorrect or inelegant ways of solving problems.
Thanks for taking the time to respond to this, especially as it's the weekend! I'll clarify a couple of points.
I understand the conventions of underscores, hence why I was a little worried that a prominent example of how to achieve what I wanted seemed to be accessing them. I was wondering if this is 'naughty' or if using 'undocumented' things was a norm. Thanks for pointing me to
flattenOffset!Ah, on reflection I managed to confuse myself and mixed up an instance of Animated and PanResponder. Disregard this.
This is true. I had a further mystery involving
shadow*styles not working on Android, but I see it has already slipped into your known issues.You're right, I did overlook it. I think my brain just skipped across it because I didn't realise more was possible.
I think your response demonstrates that a lot of the information is available, but perhaps there might be possible improvements to discoverability and structure?
Perhaps you could expand the small 'movie list' tutorial project to briefly walk through all the key parts of RN dev? Something that covers writing some features, testing them, debugging and deploying. A good example for this sort of thing, I think, is Django's tutorials. Having talked to some of the Django foundation, I know they take their docs pretty seriously.
This would hopefully give newbies like me more of a foothold in how to approach development and what tools are available in the RN toolbox.