README
A React+Redux framework with standards, conventions, and far less boilerplate
Installation
$ npm i arco --save
Summary
arco
is a framework designed to streamline a lot of the architectural configuration of a React application by providing several web-standard packages built-in, as well as an API that is built to keep boilerplate minimal.
The following packages are all included as part of arco
:
- axios for AJAX calls
- react for views
- react-dom for rendering into the browser
- react-router for routing
- react-router-redux for react-router bindings into redux
- redux for state management
- redux-actions for simplified redux action creation
- redux-immutable for use of redux with stores based on ImmutableJS
- redux-thunk for asynchronous actions (optional)
- reselect for memoized selectors
Additionally, the following concepts are applied through convention:
- ducks for encapsulated functionality modules of actions / reducer
- flux-standard-action for formatting of actions in a standard way
arco
provides a layer of abstraction over the use of these so that you can focus on implementation, but with the same sort of flexibility you would expect from each of these packages directly. Think of it as convention with configuration. Additionally, keeping in line with redux
, arco
focuses on immutability and pure functions to eliminate side effects and make testing easier.
Building an app
You can find tutorials on how to create each aspect of an arco
app in the "Tutorials" section, or select from below:
- Actions: actions consumed by your
redux
store (based onredux-actions
) - Ajax: make async calls, such as to an API (based on
axios
) - Components:
react
components that are connected to your store and enhanced by the use of pure functions - History: history used with
react-router
for the single-page application - Modules: encapsulated modules that contain
redux
actions and a reducer to manage them (based on ) - Reducers: reducer that contains state of a specific topic in your
redux
store - Rendering: rendering your
react
views into the DOM - Router: render your
react
views active in the route (based onreact-router
) - Selectors: memoized selectors for computed data to keep your stored state small (based on
reselect
) - Store: your
redux
store which encompasses the state of your entire application
Hello World example
// import from one application
import createComponent, { createModule, render } from 'arco';
// create a module for a piece of functionality in your state
const app = createModule('app');
// create actions for that module
const sayHello = app.createAction('SAY_HELLO');
// create a reducer for that module
app.createReducer({hasSaidHello: false}, {
[sayHello](state) {
return {
...state,
hasSaidHello: true
};
}
});
// create your store from an array of modules (or the module's reducers)
const store = createStore([app]);
// build your components as functional components
const App = ({hasSaidHello, sayHello}) => {
return (
<div>
<button onClick={sayHello} type="button">
Say hello
</button>
{hasSaidHello && <h1>Hello World!</h1>}
</div>
);
};
// create the component with options that allow connecting to lifecycle methods and the redux store=
const ConnectedApp = createComponent(App, {
mapStateToProps({app}) {
return app;
},
mapDispatchToProps: {
sayHello
}
});
// render in browser, pre-wired with the store
render(<ConnectedApp/>, document.body, store);
Setup
There are a couple things to be aware of when setting up arco
for your application.
React global
arco
expects there to be a global React
object for it to render components, and if you don't provide it then you will receive a React is not defined
error when attempting to render. There are two ways to fix this error:
- Create a
React
global- With
webpack
you can useProviderPlugin
- With
browserify
you can use something like browserify-global-shim - With
<script>
you just make sure to put the tag forReact
first
- With
- Import
React
from thearco
package whenever creating a component
ImmutableJS is not included
While it is a common paradigm to pair React
applications with the library ImmutableJS
, it is not included in arco
but is rather considered "opt-in". There are integration options related to your application's History and Store included in arco
, however the package itself is not included in the bundle like react
and others are. As such, if you choose to make use of it, you will need to install it yourself.
That said, Immutable is installed as a dependency to allow for those integration options, so if you are using a bundler like webpack
and are not using immutable
, it is recommended to set immutable
to be an external
in your configuration options.
Contributing
This project is in its infancy, and many more expansion capabilities are there:
- Universal app setup
- Predefined webpack / ESLint / Babel config
- CLI interface to automate creation of app scaffold
I welcome any and all ideas, but especially pull requests.
Development
Standard stuff, clone the repo and npm install
dependencies. The npm scripts available:
build
=> run webpack to build crio.js with NODE_ENV=developmentbuild:minifed
=> run webpack to build crio.min.js with NODE_ENV=productiondev
=> run webpack dev server to run example app (playground!)dist
=> runsbuild
andbuild-minified
docs
=> builds the docs viajsdoc
lint
=> run ESLint against all files in thesrc
folderprepublish
=> runscompile-for-publish
prepublish:compile
=> runlint
,test
,transpile
,dist
test
=> run AVA test functions withNODE_ENV=test
test:watch
=> same astest
, but runs persistent watchertranspile
=> run babel against all files insrc
to create files inlib