Features
- by default props are required, a saner default since it's quite easy to forget
.isRequired
- checks for unwanted additional props
- documentation (types and comments) can be automatically extracted
- additional fine grained type checks, nestable at arbitrary level
- builds on tcomb, tcomb-validation, tcomb-doc libraries
Compatibility
React: ^0.13.0
, ^0.14.0
, ^15.0.0
Prop types
@props
decorator (ES7)
The For an equivalent implementation in ES5 see the propTypes
function below.
Signature
type Props = key: string: TcombType; type PropsType = TcombStruct | TcombInterface; type Type = Props | PropsType | Refinement<PropsType>; type Options = strict?: boolean // default true; @
where
type
can be a mapstring -> TcombType
, atcomb
struct, atcomb
interface, a refinement of atcomb
struct, a refinement of atcomb
interfaceoptions
:strict: boolean
(defaulttrue
) iftrue
checks for unwanted additional props
Example (ES7)
const Gender = tenumsconst URL = t @Component { return <div> <p>thispropsname</p> ... </div> }
Unwanted additional props
By default tcomb-react
checks for unwanted additional props:
@Component { return <div> <p>thispropsname</p> </div> } ... <Person name="Giulio" surname="Canti" />
Output
Warning: Failed propType: [tcomb] Invalid additional prop(s):
[
"surname"
]
supplied to Person.
Note. You can opt-out passing the option
argument { strict: false }
.
propTypes
function (ES5)
The Signature
Same as @props
.
Example (ES5)
var t = ;var propTypes = propTypes; var Gender = tenums;var URL = t; var Card = React;
How it works
The @props
decorator sets propTypes
on the target component to use a custom validator function built around tcomb types for each specified prop.
For example, the following:
const URL = t; @Component // ...
is roughly equivalent to:
const URL = t; Component // ...MyComponentpropTypes = { if !t return '...'; } { if !t return '...'; }
The babel plugin
Using babel-plugin-tcomb you can express propTypes
as Flow type annotations:
type Gender = 'Male' | 'Female'; const isUrl = stype URL = string & $Refinement<typeof isUrl>; type Props = name: string surname: ?string age: number gender: Gender avatar: URL; @Component { return <div> <p>thispropsname</p> ... </div> }
Extract documentation from your components
parse
function
The Given a path to a component file returns a JSON / JavaScript blob containing props types, default values and comments.
Signature
Object
Example
Source
/** * Component description here * @param name - name description here * @param surname - surname description here */ @Component static defaultProps = surname: 'Canti' // default value for surname prop { return <div> <p>thispropsname</p> <p>thispropssurname</p> </div> }
Usage
const json = console
Output
Note. Since parse
uses runtime type introspection, your components should be require
able from your script (you may be required to shim the browser environment).
Parsing multiple components
{ return path;} ;
toMarkdown
function
The Given a JSON / JavaScript blob returned by parse
returns a markdown containing the components documentation.
Signature
string
Example
Usage
const json = console;
Output
## Card Component description here **Props** - `name: String` name description here- `surname: String` (optional, default: `"Canti"`) surname description here
Augmented pre-defined types
tcomb-react
exports some useful pre-defined types:
ReactElement
ReactNode
ReactChild
ReactChildren
Example
; @Component { return <div> thispropschildren </div> ; }
Support for babel-plugin-tcomb
The following types for Flow are exported:
ReactElementT
ReactNodeT
ReactChildT
ReactChildrenT
Comparison table
Type | React | tcomb-react |
---|---|---|
array | array | Array |
boolean | bool | Boolean |
functions | func | Function |
numbers | number | Number |
objects | object | Object |
strings | string | String |
all | any | Any |
required prop | T.isRequired | T |
optional prop | T | maybe(T) |
custom types | ✘ | ✓ |
tuples | ✘ | tuple([T, U, ...]) |
lists | arrayOf(T) | list(T) |
instance | instanceOf(A) | T |
dictionaries | objectOf(T) | dict(T, U) (keys are checked) |
enums | oneOf(['a', 'b']) | enums.of('a b') |
unions | oneOfType([T, U]) | union([T, U]) |
duck typing | shape | struct |
react element | element | ReactElement |
react node | node | ReactNode |
react child | ✘ | ReactChild |
react children | ✘ | ReactChildren |