79 |
95 |
96 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | 
2 |
3 | A simple Boilerplate including the best concepts and libraries of **React** and **Redux** plus some useful UI components (Toaster, Modals, Responsive Side Menu). Everything ready to build a **Performant**, **Immutable** and **Responsive** web application, including simple example of usage. Ideal for starting a project from scratch.
4 |
5 | > UI KIT concept explained in this article: [Share your happiness and your UI KIT](https://medium.com/@PierreBeard/share-your-happiness-and-your-ui-kit-5a9c92eab32a#.vfl3echw4)
6 |
7 |
8 | Check out the live version at [https://reactogo.herokuapp.com](https://reactogo.herokuapp.com).
9 |
10 | This boilerplate includes :
11 |
12 | * [Fetch API](https://github.com/github/fetch)
13 | * [Firebase](https://www.firebase.com)
14 | * [Fontastic Icons](http://fontastic.me/)
15 | * [ImmutableJS](https://facebook.github.io/immutable-js/)
16 | * [Karma Webpack](https://github.com/webpack/karma-webpack)
17 | * [React Hot Loader](http://gaearon.github.io/react-hot-loader)
18 | * [React Modal](https://github.com/rackt/react-modal)
19 | * [React Motion](https://github.com/chenglou/react-motion)
20 | * [React Router](https://github.com/rackt/react-router)
21 | * [React](https://facebook.github.io/react/)
22 | * [Redux Immutable](https://github.com/indexiatech/redux-immutablejs)
23 | * [Redux React Router](https://github.com/reactjs/react-router-redux)
24 | * [Redux](http://redux.js.org/)
25 | * [Side Menu Mobile](https://github.com/Mango/slideout)
26 | * [Stylus preprocessing](https://learnboost.github.io/stylus/)
27 | * [VelocityJS](http://julian.com/research/velocity/)
28 | * [Webpack building and webpack dev server](http://webpack.github.io/)
29 | * [ExpressJS](https://expressjs.com/api.html)
30 | * [Global UI Kit](https://medium.com/@PierreBeard/5a9c92eab32a)
31 | * SVG Spinner
32 |
33 | ## Motivations
34 |
35 | I spent a lot of time to make these differents librairies work together. For avoiding to re-do it for every projects I'm working on, I decide to build this kickstarter, and update it as soon as needed!
36 |
37 | ## Installation
38 |
39 | Simply for this project on your local machine and then :
40 |
41 |
42 | ```sh
43 | $ cd reacToGo
44 | $ npm install
45 | $ npm run start
46 | ```
47 |
48 | And go to [localhost:3000](http://localhost:3000) in your favourite browser.
49 | It will start the ```webpack-dev-server``` on the 3000 port and proxy all the requests to your future production server (expressjs) on the port 9000. This enable to have automatic reload on server side code update.
50 |
51 | Also, the ```hot``` mode is set to true, i.e. you can update the style, the JSX code and the app will be updated keeping the state without reloading the page.
52 |
53 | ## Environement variables
54 |
55 | You need to set up your Firebase environment variable to have the login system. In your firebase app, you need to set up the facebook auth and put this in your variables :
56 |
57 | ```
58 | export FIREBASE_API_KEY="API KEY"
59 | export FIREBASE_AUTH_DOMAIN="FULL AUTH DOMAIN"
60 | export FIREBASE_DATABASE_URL="FULL DBB URL"
61 | ```
62 |
63 | Thanks to the ```DefinePlugin``` the ```NODE_ENV='production'``` for productions build.
64 |
65 | ## Features
66 |
67 | * Stylus: There is a default font and class in the `style` folder you can use
68 | * Images: Webpack handle the loading of all your images and files : `file-loader`
69 | * VelocityJS: Powerful animation lib to give life
70 | * React Router: Handle basic navigation between pages, part of the global state of the app.
71 | * React Motion: Physical animation lib
72 | * UI Kit: the `/style/ui-kit.json` file is included globally. You can access to the value with `UI`. It contain all the JS var needed to build your UI kit (breakpoints, animations, size...)
73 | * Media Queries: Included in the global state of the app. Accessible with functions in ```globals/style.js```.
74 | * Data : Handle by Redux in a global IMMUTABLE state of the app. Check the model section underneath.
75 | * Firebase facebook login
76 | * React Modals
77 | * React Hot Loader: Update your react components without reload the page and keeping the main state!
78 | * Side Menu responsive
79 |
80 | ## UI Kit and Customization
81 |
82 | #### UI Kit
83 |
84 | The UI KIT is defined is the ```style/ui-kit.json```. It's accessible in both JS and Stylus with create only one source of truth for the UI Kit of the app :
85 | - JS: It's loaded with the ```json-loader``` of webpack and exposed globally via the ```ProvidePlugin``` under the name of ```UI```. So you can simply use it for inline-style directly in the React components files without even require it:
86 |
87 | ```js
88 | let s = getStyle();
89 |
90 | let MyReactComp = () =>
My React Comp
;
91 |
92 | function getStyle() {
93 | return {
94 | container: {
95 | textAlign: 'center',
96 | marginTop: 60,
97 | color: UI.lightGreen,
98 | },
99 | };
100 | }
101 | MyReactComp.displayName = 'MyReactComp';
102 |
103 | export default MyReactComp;
104 | ```
105 |
106 |
107 | - STYLUS/CSS: The same file ```style/ui-kit.json``` is also loaded in the ```style/app.styl```. So the same UI-KIT can be use also for define main app classes if needed:
108 |
109 | ```html
110 | .button
111 | padding: 10px
112 | box-shadow: inset 0px -2px 0px rgba(0,0,0,0.10)
113 | font-size: fontSM px
114 | display: inline-block
115 | border-radius: 2px
116 | text-align: center
117 | cursor: pointer
118 |
119 | @media (min-width: breakpointT px)
120 | .button
121 | padding: 10px 20px
122 |
123 | .button-primary
124 | background-color: lightGreen
125 | color: lightWhite
126 | transition: background-color 0.4s;
127 | .button-primary:hover
128 | background-color: darkGreen
129 | ```
130 |
131 | This way, you can both use inline-style or stylus or both at the same time without any duplication of UI-KIT and then keep the things tidy!
132 |
133 | ```js
134 | let s = getStyle();
135 |
136 | let MyReactButton = () =>
My React Button
;
137 |
138 | function getStyle() {
139 | return {
140 | container: {
141 | textAlign: 'center',
142 | marginTop: 60,
143 | color: UI.lightGreen,
144 | },
145 | };
146 | }
147 | MyReactButton.displayName = 'MyReactButton';
148 |
149 | export default MyReactButton;
150 | ```
151 |
152 | ## Redux Model
153 |
154 | Thanks to redux and its middlewares, the app state contain everything needed to modelling the UI of your app. Here is the schema of the current model (customizable of course):
155 | * Routing: Thanks to [Redux React Router](https://github.com/reactjs/react-router-redux) the current route and the params are hosted in the global state and handle via Action/Reducer.
156 | * Viewport:
157 | * isMobile: bool
158 | * isTablet: bool
159 | * isDesktop: bool
160 | Used for handle the media queries with inline css. Theses state are handled in the ```reducers/viewport-reducer.js``` reducer. Each time the window is resized, a debounced function will dispatch the action and update the state. Hence, in each components connected with [React Redux](https://github.com/rackt/react-redux) will be re-render. This way, if you use the ```handleStyle``` function contained in the ```globals/style.js``` you can describe in inline css the style of your component on three differents viewports. Check the function for more informations
161 | * Session:
162 | * Token: auth token by Firebase
163 | * uid: User id
164 | * provider: facebook
165 | * user: User info from facebook
166 | * Modals:
167 | * isLoginModalOpen: bool
168 | * Side Menu:
169 | * isSideMenuOpen: bool
170 | * Toaster:
171 | * List of messages: []
172 |
173 | ## Redux Librairies
174 |
175 | * [Redux](http://redux.js.org/)
176 | * [React Redux](https://github.com/rackt/react-redux): Connection with React comp
177 | * [Redux React Router](https://github.com/reactjs/react-router-redux): Bridge with React Router
178 | * [Redux Thunk](https://github.com/gaearon/redux-thunk): Enable to dispatch functions
179 | * [Redux Logger](https://github.com/fcomb/redux-logger): Debugger in the console
180 | * [Redux Immutable](https://github.com/indexiatech/redux-immutablejs): Global immutable state
181 |
182 | ## Production
183 |
184 | All the build scripts are in the ```package.json``` file. If you want to build locally, simply run :
185 |
186 | ```sh
187 | $ npm run build
188 | ```
189 |
190 | It will trigger the ```webpack.production.config.js``` build system and will put you everything under the ```dist``` folder.
191 |
192 | ## Tests
193 |
194 | The unit test are done with [Karma Webpack](https://github.com/webpack/karma-webpack) and triggered after each build (or deployments). You can launch them manually via:
195 |
196 | ```sh
197 | $ npm run test
198 | ```
199 |
200 | The command is described in the ```package.json``` file. So far only the reducers functions are tested as examples. The current configuration will take all the files ending with ```*.spec.js``` and process these with [Karma Webpack](https://github.com/webpack/karma-webpack).
201 |
202 | It's using [Mocha](https://mochajs.org/) for its simplicity, [Expect](https://github.com/mjackson/expect) for the assertions and [PhantomJS](https://github.com/ariya/phantomjs) for running those in the terminal.
203 |
204 | The whole testing configuration is available in the ```/tests/karma-conf.js```.
205 |
206 | ## Deployment
207 |
208 | For deploying the APP, simply push it to your CI app. I will trigger the build automatically with:
209 |
210 | ```sh
211 | $ npm postinstall
212 | ```
213 |
214 | If you are using [Heroku](https://www.heroku.com) the ```Procfile``` is already set up.
215 |
216 | If you want to do it manually, simply copy the following command and customize it if needed:
217 | ```sh
218 | webpack --config webpack.production.config.js
219 | ```
220 |
221 | ## Webpack
222 |
223 | Here's the list of the Webpack dependencies and plugins:
224 |
225 | * [Webpack-Dev-Server](https://webpack.github.io/docs/webpack-dev-server.html): Used for development.
226 | * [DedupePlugin](https://github.com/webpack/docs/wiki/optimization) and [UglifyJsPlugin]((https://github.com/webpack/docs/wiki/optimization)): for optimizing the build size.
227 | * [ProvidePlugin](https://webpack.github.io/docs/list-of-plugins.html#provideplugin): For exposing global values such as the UI KIT or Velocity.
228 | * [DefinePlugin](https://webpack.github.io/docs/list-of-plugins.html#defineplugin) For setting up the NODE_ENV
229 |
230 | ## Contributions
231 |
232 | Every contributions is more than welcome! Simply create a PR and I will check it asap!
233 |
--------------------------------------------------------------------------------