From ff0a5a5dcbe90fcafd247ace3a9bcfc4c93b90f7 Mon Sep 17 00:00:00 2001 From: Matthieu Napoli Date: Tue, 25 Sep 2018 14:42:26 +0200 Subject: [PATCH] Improve the README before the blog post --- README.md | 44 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1d62395e1..0bee59afa 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,30 @@ This project is a [React Native](https://facebook.github.io/react-native/) boile The boilerplate provides **an architecture optimized for building solid applications** through separation of concerns between the UI and business logic. It is extremely documented so that each piece of code that lands in your application can be understood and used. +## Architecture + +The driving goal of the architecture of the boilerplate is separation of concerns. Namely: + +- **Presentational components are separated from containers** (aka "screens"). + + Presentational components are small components that are concerned with *how things look*. Containers usually define whole application screens and are concerned with *how things work*: they include presentational components and wire everything together. + + If you are interested you can [read more about it here](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0). + +- **State is managed using global [Redux](https://redux.js.org/) stores**. + + When applications grow, sharing state and its changes can become very hard. Questions like "How can I access this data?" or "When did this change?" are common, just like passing data around components just to be able to use it in nested components. + + With Redux, state is shared using global *stores*, and changes are predictable: *actions* are applied by *reducers* to the state. While the pattern can be a bit much for small projects, the clear separation of responsibilities and predictability helps with bigger applications. + + If you are interested you can [read more about it here](https://redux.js.org/introduction/motivation). + +- **Application side-effects (API calls, etc.) are separated from UI and state manipulation using [Redux Saga](https://redux-saga.js.org/)**. + + Using Redux Saga has two benefits: keeping application side-effects and related business logic out of UI components, as well as executing that logic in an asynchronous way without ending in callback hell. + + Sagas are triggered by Redux actions and can also trigger Redux actions to alter state. By using JavaScript generators (`yield`), sagas are written in a synchronous-like manner while still executing asynchronously. + ## Content The boilerplate contains: @@ -18,9 +42,7 @@ The boilerplate contains: - [apisauce](https://github.com/infinitered/apisauce) (v0.15) to make [axios](https://github.com/axios/axios) even better - [prettier](https://prettier.io/) and [eslint](https://eslint.org/) preconfigured for React Native -## Updates - -The boilerplate will follow new React-Native releases as soon as libraries and tools used here are compatible. +The boilerplate includes an example (displaying the current weather temperature) from UI components to the saga. The example is easy to remove so that it doesn't get in the way. ## Directory layout @@ -35,6 +57,10 @@ The boilerplate will follow new React-Native releases as soon as libraries and t For more information on each directory, click the link and read the directory's README. +## Updates + +The boilerplate will follow new React-Native releases as soon as libraries and tools used here are compatible. + ## Requirements Node 8 or greater is required. Development for iOS requires a Mac and Xcode 9 or up, and will target iOS 9 and up. @@ -81,8 +107,14 @@ This project is released under the [MIT License](LICENSE). [TheCodingMachine](https://www.thecodingmachine.com/) is a web and mobile agency based in Paris and Lyon, France. We are [constantly looking for new developers and team leaders](https://www.thecodingmachine.com/nous-rejoindre/) and we love [working with freelancers](https://coders.thecodingmachine.com/). You'll find [an overview of all our open source projects on our website](https://thecodingmachine.io/open-source) and on [Github](https://github.com/thecodingmachine). -## See also +## Alternative boilerplates + +We looked into existing boilerplates before starting this project, and while many of them are awesome, we did not find what we were looking for. + +The most popular is [mcnamee's Starter Kit](https://github.com/mcnamee/react-native-starter-kit), which is unfortunately [limited by *Expo*](https://facebook.github.io/react-native/docs/getting-started#caveats) and misses Redux Saga. + +If we look at the rest (and ignore unmaintained projects), many popular boilerplates are too opinionated: they include 3rd party services or very strong architecture choices that we are not comfortable with. To name a few: [Snowflake](https://github.com/bartonhammond/snowflake) runs with a Hapi Server running on Redhat OpenShift, [Hasura's boilerplate](https://github.com/hasura/react-native-auth-boilerplate) uses Hasura's SaaS for authentication, [Apollo's StarterKit](https://github.com/sysgears/apollo-universal-starter-kit) is targeted at GraphQL using Apollo, the [Meteor Boilerplate](https://github.com/spencercarli/react-native-meteor-boilerplate) targets Meteor… -Here are alternative boilerplates that you may want to check out: +Finally some did not contain the architecture we are looking for (the separation of concerns with Redux, Sagas, etc.), for example [re-start](https://github.com/react-everywhere/re-start). -- [Ignite boilerplate](https://github.com/infinitered/ignite-ir-boilerplate-andross): this boilerplate is much more opinionated and packed that this one, we wanted something lighter which is why we did no go with it +One interesting exception is [Ignite IR Boilerplate "Andross"](https://github.com/infinitered/ignite-ir-boilerplate-andross), but after consideration we decided not to use it because of the large amount of unnecessary code/components it provided.