HELLO: react-black-triangle (and Maxim) are at v0.1 - if you find this neat, you can help make it even better by letting me know where you'd like to see more documentation!
react-black-triangle provides you with the code and conventions you need to get straight into building your React-based app.
Happiness is six lines away
Prerequisites: node.js and git
git clone email@example.com:jamesknelson/react-black-triangle.git [your-repo-name] cd [your-repo-name] npm install npm install -g gulp npm start npm run open # (from a different console window, otherwise open localhost:3000)
Presto, Black Triangle!
Why use react-black-triangle?
- Your directory structure is sorted as soon as you
- ES6 compilation and automatic-reloading development server are all handled by
- Maxim (based on RxJS) makes your data flow easy to reason about
- CSS conventions and helper functions completely eliminate bugs caused by conflicting styles
- Elegant routing is included without depending on the confusing
- A simple layout is included to help you get started on the important stuff right away
- Comes with a cool spinning Black Triangle - how fucking awesome is that?!
Put your name on it:
- Update name and author in package.json
- Update app title in
- Restart the dev server (make sure to do this after any changes to
Make sure your editor is happy
- Setup ES6 syntax highlighting on extensions
Remove the stupid black triangle and any references to it:
- Add a route to
- Add a nav menu item in
- Add a component for it in
- Add the new component and route to
- Bask in the glory of your creation
- Don't forget to commit your changes and push to bitbucket or github!
Show your friends
gulp distto output a web-ready build of your app to
Your data - including routes, authentication, view model data, and anything else you can imagine - is managed by Maxim.
Maxim is similar to Facebook's Flux, in that data flow is unidirectional. Events start at your Controls, then flow through your Models, Reducers, Actors, and finally through your Components to the user's screen.
Maxim gives you four classes with well defined responsibilities:
All possible actions which can affect the state of your model are defined in these Controls.
control file defines a number of action functions. Action functions can do things which change the outside world (like making HTTP requests or setting timers), and can call other actions in the same control module (as long as the calls are in a separate tick).
Once an action has run any necessary code, it should call
this to emit an event to be processed by model modules.
Models take the Rx.Observable objects from the above action files as inputs. Each model returns a single observable itself, which represents the state of that model.
Reducers take the Rx.Observable objects produced from models and other reducers, and further process them into more Rx.Observables.
Actors subscribe to the Rx.Observable objects from your Model and Reducer files, using the result to change the outside world through actions such as displaying a UI or calling further control actions.
Of course, having an actor which is called with the latest version of your data is only half the problem - you need to effectively communicate this data to your users. We accomplish this with (surprise!) React!
To help concenctrate on actually building your application, use these conventions when building your user interface:
Applicationcomponent every time any model/reducer data changes
- Components should access control actions through their
BlackTrianglePage.jsxfor an example)
- Data should be passed as props, and not passed through
- Make sure each of your components have their own directory under
src/components(other than the special
- Each component should inherit from the Base component (which provides helpers for genrating classes, see
- Control Actions are
- Each component's root element should have a class named after the component itself
- Each component should accept a
classNameprop which adds any specified classes to it's own classes
Style selectors should always be a single class, and optionally a pseudo-selector. For example:
.NavMenu .Linkis bad
this.cmethod on every component which inherits from base helps with making these methods.
controlcontains actions which can be called by actors
modelmaintains a single value, updating it based on control events
src/reducers- Further process the values of models and other reducers
src/actors- Interfact with the world based on changes to your model
src/components- React components and their associated stylesheets
src/theme- Global CSS (you generally don't put anything here except imports for component stylesheets)
build- Intermediate files produced by the development server. Don't touch these.
src/utils- Pure functions which you may want to use across your entire project go here
src/static- Files which will be copied across to the root directory on build
Individual modules (documentation coming soon):
And other files:
index.htmlfor changes and copy them across to