Preface
While React Redux Boilerplate is a ready to use workflow boilerplate for frontend client development ( we welcomed pull request, please ), we are also using that for our recruiting purpose.
The technologies in this workflow boilerplate shows case a subset of technologies
we are currently using within our team, and we are trying to give our candidates confidence that by working with us, they will be using decent technologies as well as stay relevant to the industry. And that is what our team strongly believed in - technology innovation and promoting developers' relevancy in the industry.
If you are interested in working with us, feel free to send a message to iroy2000.
Note: This boilerplate is not to show case how to develop in React / Redux, it is a boilerplate that hook everything up for you that you can develop on, so you won't see complicated example here.
React Redux Boilerplate
React Redux Boilerplate
is a workflow boilerplate that make life easier for developers by providing a virtual development environment and production ready build process framework out of the box.
React Redux Boilerplate
is for developing client side application. So, if you are looking for:
Isomorphic (Universal) support
, feel free to add server side support to it, or you can use something like react-server or electrode
Features / Benefits
- React
- Redux
- Webpack
- Reselect
- ES6
- ImmutableJS
- PostCSS ( it support CSS modules, but we also recommended B.E.M style )
- ESLint integrated
- Integrated with fancy cli dashboard
- Hot Module Reload during development
- CSS / HTML / JS minification / Image optimization when built
- JS code duplication removal during built
- Built-in process to deploy files directly to S3 ( optional )
- Built-in lightweight config system
- Built-in support for multiple device concurrent debugging and easy network sharing options with your peers from your laptop.
- When you build it, it will optimize JS, HTML and image assets ... etc, for you ( production quality )
- Build system functionality are powerful and easy to configure ( webpack )
- Minimal setup time and allow you to invest into things that matters
- Everything automatic, you just care about development, nothing else \o/ Yeah ?!
If you are interested, please read the package.json
for all installed modules and plugins.
Table of Contents
- Installation
- Initialize your project
- Suggested Workflow
- Developing Template
- Integration Note
- QA
- Knowledge Base Reading
- How to Contribute
Installation
Prerequisite
You need to have Node.js installed.
Post Installation
If you would like to have Redux debug capabilities, you can download this Chrome extension Redux DevTool
Initialize your project
Now run the following commands in your terminal
NOTE: You only need to run this once!
$ npm install # This will install the necessary packages to use the app
That's it!
To run the app in Development Mode
$ npm run dev
Wait about 5 - 10 seconds for your development environment to initialize.
When it finishes, open your browser and go to http://localhost:8080/
If you see the landing page, it means you have set up everything successfully.
List of NPM Commands
$ npm run dev # build and watch, but javascript not minified
$ npm run build # build a minified production version
$ npm run lint # linting
$ npm run test # run test
Suggested Workflow
After you check out the repo, I will usually do the following :
- Go to your project root in your host machine ( e.g. your Mac )
- Run
npm run dev
- Go to your browser and go to
localhost:8080
- Make code changes
- Watch your code changes reflect on browser without refreshing
- Repeat your development steps
That's very easy, isn't it?
Production Preview
React Redux Boilerplate supports production preview, which means that you can run the production build job and see how it looks like in production.
- Run
npm run build
and wait until it is done (it'll take awhile) - Go to the project
docroot
, you will see aindex.html
- Open that
index.html
in your browser, and that is the build version that just got generated
That's very easy, isn't it?
npm run dev
v.s. npm run build
Difference between npn run dev
is best to do JS / CSS only changes, and it comes with live reload functionality
npm run build
is for testing what happen if your frontend assets are optimized ( production level code )
Please let me know if you have better work flow suggestion!!
Configuring your application
If you look at folder config
, there are four files
default.json
- all default configuration
development.json
- when you run npm run dev
, it will pull configuration from that file
release.json
- when you have NODE_ENV=release, it will use this configuration
production.json
- when you have NODE_ENV=production, it will use this configuration
We are using node-config, they have a pretty easy to understand documentation.
And in your config file ( json config file ), whatever you put inside the app
, it will be injected into the client application and you can access to your app
config data by using __CONFIG__
variables.
Let's say you have a config like the following
{
"app": {
"apiURL": "http://foo.bar/"
}
}
In your React application, you can access this variables
__CONFIG__.apiURL
Developing Template
The docroot/index.html
is a generated artifact. If look at our sample template at src/assets/template/_default.html
, the docroot/index.html
is generated from that file.
We are using HTML Webpack Plugin to generate the docroot/index.html
.
- If you are developing a single page application, you probably can reuse that file or customize it.
- If you are building multiple pages application, please read the HTML Webpack Plugin documentation for template development and how to configure it.
[Note] - Most of the use case of the html template system so far is for testing purpose for your dev and build enviornment before you start integration. If all you need is a static template, you are good; but if your application requires a server side processing, you will need to integrate the artifacts with the language of your choice. Please read Diagrams
section for how to integrate with other server side language.
Integration Note
How to integrate with other server side framework ?
When you run npm run build
, it will generate a meta data file assets.json
with the list of generated frontend artifacts. Think about that as a contract / interface for your server side framework.
And your framework just need to consume that meta information as integration point.
And this boilerplate has a process integrated to upload artifacts ( assets.json and generated client ifacts ) to S3 / cloudfront. One of the integration path is the consumer
can query against s3 for the assets.json, and use the information in assets.json to get the artifacts which is uploaded to S3 / cdn.
QA
-
How to activate S3 support ?
-
S3 upload is optional here, but if you want to activate that, please go to your config and make
"s3Deploy": true
and fill up thes3
config ( bucket, accessKey ... etc). Remember that you can put the same config in different environment in case you want each one has different behavior. Below is anexample
inconfig/default.json
// Example in config/default.json // You can overwrite default using your other config file // ======================================================== // default.json - global // development.json - development ( NODE_ENV=development) // release.json - test/release ( NODE_ENV=release) // production.json - production ( NODE_ENV=production) // ======================================================== { "s3Deploy": true, "s3": { "bucket": "", // aws bucket "accessKey": "", // asw access key "accessSecret": "", // aws secret key "defaultCDNBase": "" // append cdn url to your build assets }, }
-
-
What is our standard to control our npm module dependencies ?
- We are using
^version
, it means "Compatible with version". The reason we are using^version
is simply we want the ability for us to roll back to previous working version together with the source code.
- We are using
-
How to add javascript unit test ?
- All React JS test are under _tests_ directory and this tool will find all the test, you don't need to do anything besides putting your test in, but please use a structure that mimic your source location that you are testing, or it will create confusion.
-
What is B.E.M style ?
- B.E.M is short for
Block, Element, Modifier
and is a naming convention for classes in HTML and CSS. Its goal is to help developers better understand the relationship between the HTML and CSS and make our code base more maintainable.
- B.E.M is short for
Knowledge Base Reading
- Thinking in React
- Redux
- redux-cli documentation
- Lazy Loading and Code Split for React Route
- Learning SASS
- Learning PostCSS
- Jest = Awesome JS Testing Framework
- Synchronization of props with state is an anti-pattern
- B.E.M 101
- Isomorphic JavaScript, The Future of Web Apps
How to Contribute
We welcome anyone to send us pull request to improve this boilerplate, the goal is to make it better from time to time and we all can learn from it.
This boilerplate will be maintained separately. So please do not check in any business logic to it unless it is for example purpose.
License
In theory, knowledge should be free, so please visit wtfpl for this boilerplate license if you really care.