This starter kit provides you with the code and conventions you need to get straight into building your React/Redux based app.
Prerequisites: node.js and git
git clone https://github.com/unicorn-standard/starter-kit.git your-repo-name
cd your-repo-name
npm install
npm start
npm run open # (from a different console window, otherwise open localhost:3000)
Presto, you've got a ready-to-customise application!
- Your directory structure is sorted as soon as you
git clone
- ES6 compilation and automatic-reloading development server are configured for you with webpack and Babel
- Redux is an incredibly simple way of modelling your data, with great community support
- React is an incredibly simple way of rendering your views, and is maintained by Facebook
- Simple uniloc-based routing is included - easy to understand, and easy to customize
- The Pacomo CSS conventions eliminate bugs caused by conflicting styles
- The actors pattern allows you to easily react to changes on your store without forcing a re-render
- Your redux store is already configured with navigation, data and view models
- Comes with views, layouts and reducers for a simple document editor!
- Update name, desription and author in
package.json
- Update app title in
src/index.html
- Restart the dev server (make sure to do this after any changes to
src/index.html
)
- Setup ES6 syntax highlighting on extensions
.js
and.jsx
(see babel-sublime)
- Add a route to
src/constants/ROUTES.js
- Add a nav menu item for your route in
src/components/ApplicationLayout.jsx
- Add a component for your route in
src/components
- Add reducers and actions for your component's view model in
src/actions
andsrc/reducers/view
- Add any data models which your component reqiures in
src/reducers/data
- Add a container to map your store's
state
anddispatch
to component props insrc/containers
- Configure your route in
src/Application.jsx
- Bask in the glory of your creation
- Don't forget to commit your changes and push to Bitbucket or GitHub!
- Run
gulp dist
to output a web-ready build of your app todist
main.js
is the entry point to your application. It defines your redux store, handles any actions dispatched to your redux store, handles changes to the browser's current URL, and also makes an initial route change dispatch.
Most of the above will be obvious from a quick read through main.js
- if there is one thing which may strike you as "interesting", it'll be the block which handles actors.
Read the introduction to actors
Each time your store's state changes, a sequence of functions are called on the current state of your store. These functions are called actors.
There is one important exception to this rule: actors will not be called if main.js
is currently in the midst of calling the sequence from a previous update. This allows earlier actors in a sequence to dispatch actions to the store, with later actors in the sequence receiving the updated state.
The code which accomplishes this is very small:
let acting = false
store.subscribe(function() {
// Ensure that any action dispatched by actors do not result in a new
// actor run, allowing actors to dispatch with impunity.
if (!acting) {
acting = true
for (let actor of actors) {
actor(store.getState(), store.dispatch.bind(store))
}
acting = false
}
})
The actor is defined in src/actors/index.js
. By default, it runs the following sequence:
- redirector - dispatch a navigation action if the current location should redirect to another location
- renderer - renders your component with React
Your model (i.e. reducers and actions) is pre-configured with three parts:
The navigation
state holds the following information:
location
is the object which yourROUTES
constant'slookup
function returns for the current URL. With the default uniloc-basedROUTES
object, this will have a stringname
property, and anoptions
object containing any route parameters.transitioning
is true if a navigationstart
action has been dispatched, but the browser hasn't changed URL yet
The data
state can be thought of as the database for your application. If your application reads data from a remote server, it should be stored here. Any metadata should also be stored here, including the time it was fetched or its current version number.
The view
state has a property for each of the view's in your app, holding their current state. For example, form state should be stored in the view models.
src/actions
- Redux action creatorssrc/actors
- Handle changes to your store's statesrc/components
- React components, stateless where possiblesrc/constants
- Define stateless datasrc/containers
- Unstyled "smart" components which take your store'sstate
anddispatch
, and possibly navigationlocation
, and pass them to "dumb" componentssrc/reducers
- Redux reducerssrc/static
- Files which will be copied across to the root directory on buildsrc/styles
- Helpers for stylesheets for individual componentssrc/utils
- General code which isn't specific to your applicationsrc/validators
- Functions which take an object containing user entry and return an object containing any errors
Other directories:
build
- Intermediate files produced by the development server. Don't touch these.dist
- The output ofgulp dist
, which contains your distribution-ready app.config/environments
- The build system will assign one of these to theenvironment
module, depending on the current build environment.
Main application files:
src/Application.jsx
- Your application's top-level React componentsrc/index.html
- The single page for your single page applicationsrc/main.js
- The application's entry pointsrc/main.less
- Global styles for your application
Main build files:
- Watch
static
andindex.html
for changes and copy them across tobuild
when appropriate