Stabilized public API

[petehunt]

One of the things holding us back right now is that we don't have a stable public API. I'd really like to cut Instagram over to the npm version of React but unfortunately it doesn't include some of the addons that we need because of this issue. I'd like to propose the following changes:

Consistent, iterable this.props.children

this.props.children gets wrapped in a new ReactChildIterator object -- basically a thin wrapper around ReactChildren.map(). This means that people can actually introspect this.props.children without assuming it's an array or a nested object or something.

I don't think memory utilization is a big problem today so I think this change would be OK, especially if it is implemented lazily. I know that @dnolen wants something like this too if he can plug in his own lazy child data structure.

I do think it's important we solve this. Another option I was thinking of was putting mapChildren() on ReactCompositeComponent -- but that begs the question of adding onlyChild() as well and I think the API would become confusing.

cloneWithProps() on ReactComponent

I think this function is very helpful and hard to use externally right now. Adding it to the public API of ReactComponent makes sense to me. Does anyone think that there is potential for overuse here?

Public injection APIs

I think we should centralize all injection points for React in a ReactInjection module and make it public as React.injection. There's no reason why you should need to check out the repo to configure a custom React.

Rename lib/ to internal/ in the react npm module

For many addons we'll need to do stuff like require('react/lib/ReactUpdates') for the foreseeable future. Let's just embrace it for now and rename lib/ to internal_do_not_use_or_you_will_be_fired/ so non-core projects don't depend on this.

Put each add-on into its own npm module

Everything in https://github.com/facebook/react/pull/745/files

Add new react-svg npm package

This will export the DOMPropertyConfig which can be injected with the new public ReactInjection APIs.

Use wzrd.in for package builds

We can put our own cache in front of it so we are good citizens. This way people can build their own react-whatever.min.js without us having to provide a million builds or a config tool.

[brainkim]

What's the rationale behind each add-on needing its own npm package? Right now I'm doing things like var cx = require('react/lib/cx'). Can't we just create an addon directory in the react package? Are we worried about tree-shaking or non-commonjs builds?

[zpao]

@brainkim - cx/classSet doesn't need React at all. I could see us putting that into a standalone npm/bower/whatever module with no real association with React.

[petehunt]

@brainkim wzrd.in won't package them unless they are require()d somewhere. So we'd either be unable to get the addons or force all users to include all of the addons, which sucks too.

[brainkim]

@zpao @petehunt Hm. I think I understand where you're coming from. It's just that, for instance, classSet is a ten line function, and having that be its own npm module replete with its own sem-ver number and README seems a bit excessive, you feel me? Lemme look a bit into wzrd.in and see if there's any other solutions.

[zpao]

You say that, but npm is all for shipping your 10 line function as a module.

[brainkim]

You know what? Go for it. I just love that you guys are full-on adopting commonjs.

[andreypopp]

@petehunt that sounds like a limitation of wzrd.in which I think one can request them to fix.

@zpao I wish npm has the ability to host just a single js file as a package with inline metadata (like @author and so on)

[monsanto]

I'm not sure if this is the place, but I'd like to give a +1 to exposing cloneWithProps somewhere more convenient. I would change the name though--clone implies that component descriptions are mutable. It doesn't really make sense to talk about cloning immutable objects. I'd call it something like addProps or mergeProps.

[gaearon]

I’m not sure a lot of this is still actionable now, and if it is, it’s best if we re-raise the relevant parts as separate issues.

For the reference, here’s what we have right now:

Consistent, iterable this.props.children

React.Children should cover that.

cloneWithProps() on ReactComponent

React.cloneElement() should be good.

Put each add-on into its own npm module

Technically done, and we’ll be separating some of them out of the main repo after 15.

Public injection APIs
Rename lib/ to internal/ in the react npm module
Use wzrd.in for package builds

Maybe we’ll come back to these but not a priority right now.

Add new react-svg npm package

Something we’ve been considering but we decided to delay this as well.