Improve developer experience with better documentation and type safety #82
Description
I've been trying to accomplish relatively simple tasks in PlayCanvas React, like changing the color of an element, but I'm finding it surprisingly challenging due to several issues.
This has resulted in me constantly switching between the PlayCanvas React source code, API documentation, and even enlisting Claude 3.7 with Perplexity for deep research - yet we still struggle to solve relatively simple issues within reasonable timeframes that I expect could have been a breeze with some small improvements to the DX.
Documentation Gaps
The examples in the documentation are insufficient for common use cases
For instance, the useMaterial hook documentation lacks concrete examples showing how to properly manipulate material properties. I am not very familiar with the PlayCanvas engine in the first place, and adding this on top with no clear demonstration of escape hatches to do it the "native PlayCanvas" way makes this needlessly time-consuming.
Type Issues
The TypeScript types are not restrictive enough to provide meaningful guidance
For example (no feedback here that something and somethingelse are absolutely not expected):
in other cases, copying working examples gives type errors, which is
quite misleading and confuses both me and Cursor, forcing me to @tsignore everywhere:
(from https://github.com/playcanvas/react/blob/main/packages/docs/src/content/physics.mdx)
Error Handling
There are no warnings or error messages when unfamiliar props are passed
This makes debugging significantly more difficult as invalid inputs silently fail.
Suggested Improvements
- More comprehensive examples covering common use cases
- Strongly typed examples
- Stricter TypeScript types to provide better developer guidance
- Improved JSDoc comments on all component props and hooks
- Warning/error messages for invalid prop usage
I really appreciate the work that's gone into this library and I'm excited to use it for my projects. These improvements would make the developer experience much more intuitive and productive.