- Requirements
- Installation
- Running the Project
- Project Structure
- Live Development
- Routing
- Testing
- Building for Production
- Deployment
- node
^5.0.0 - yarn
^0.23.0or npm^3.0.0
$ git clone https://github.com/Xinhe998/meracle-website.git <my-project-name>
$ cd <my-project-name>$ yarn # Install project dependencies (or `npm install`)$ yarn start # Start the development server (or `npm start`)While developing, you will probably rely mostly on yarn start; however, there are additional scripts at your disposal:
yarn <script> |
Description |
|---|---|
start |
Serves your app at localhost:3000 |
build |
Builds the application to ./dist |
test |
Runs unit tests with Karma. See testing |
test:watch |
Runs test in watch mode to re-run tests when changed |
lint |
Lints the project for potential errors |
lint:fix |
Lints the project and fixes all correctable errors |
.
├── build # All build-related code
├── public # Static public assets (not imported anywhere in source code)
├── server # Express application that provides webpack middleware
│ └── main.js # Server application entry point
├── src # Application source code
│ ├── index.html # Main HTML page container for app
│ ├── main.js # Application bootstrap and rendering
│ ├── normalize.js # Browser normalization and polyfills
│ ├── components # Global Reusable Components
│ ├── containers # Global Reusable Container Components
│ ├── layouts # Components that dictate major page structure
│ │ └── PageLayout # Global application layout in which to render routes
│ ├── routes # Main route definitions and async split points
│ │ ├── index.js # Bootstrap main application routes with store
│ │ ├── Home # Fractal route
│ │ │ ├── index.js # Route definitions and async split points
│ │ │ ├── assets # Assets required to render components
│ │ │ ├── components # Presentational React Components
│ │ │ └── routes ** # Fractal sub-routes (** optional)
│ │ └── Counter # Fractal route
│ │ ├── index.js # Counter route definition
│ │ ├── container # Connect components to actions and store
│ │ ├── modules # Collections of reducers/constants/actions
│ │ └── routes ** # Fractal sub-routes (** optional)
│ ├── store # Redux-specific pieces
│ │ ├── createStore.js # Create and instrument redux store
│ │ └── reducers.js # Reducer registry and injection
│ └── styles # Application-wide styles (generally settings)
└── tests # Unit tests
Hot reloading is enabled by default when the application is running in development mode (yarn start). This feature is implemented with webpack's Hot Module Replacement capabilities, where code updates can be injected to the application while it's running, no full reload required. Here's how it works:
-
For JavaScript modules, a code change will trigger the application to re-render from the top of the tree. Global state is preserved (i.e. redux), but any local component state is reset. This differs from React Hot Loader, but we've found that performing a full re-render helps avoid subtle bugs caused by RHL patching.
-
For Sass, any change will update the styles in realtime, no additional configuration or reload needed.
yarn add --dev redux-devtools redux-devtools-log-monitor redux-devtools-dock-monitorWe use react-router route definitions (<route>/index.js) to define units of logic within our application. See the project structure section for more information.
To add a unit test, create a .spec.js file anywhere inside of ./tests. Karma and webpack will automatically find these files, and Mocha and Chai will be available within your test without the need to import them. Here are a few important plugins and packages available to you during testing:
Some of the assertions available from chai use magical getters. These are problematic for a few reasons:
- If you mistype a property name (e.g.
expect(false).to.be.tru) then the expression evaluates to undefined, the magical getter on thetrueis never run, and so your test silently passes. - By default, linters don't understand them and therefore mark them as unused expressions, which can be annoying.
Dirty Chai fixes this by converting these getters into callable functions. This way, if mistype an assertion, our attempt to invoke it will throw due to the property being undefined.
// This silently passes because the getter on `true` is never invoked!
it('should be true', () => {
expect(false).to.be.tru // evalutes to undefined :(
})
// Much better! Our assertion is invalid, so it throws rather than implicitly passing.
it('should be true', () => {
expect(false).to.be.tru() // `tru` is not defined!
})Out of the box, this starter kit is deployable by serving the ./dist folder generated by yarn build. This project does not concern itself with the details of server-side rendering or API structure, since that demands a more opinionated structure that makes it difficult to extend the starter kit. The simplest deployment strategy is a static deployment.
Serve the application with a web server such as nginx by pointing it at your ./dist folder. Make sure to direct incoming route requests to the root ./dist/index.html file so that the client application will be loaded; react-router will take care of the rest. If you are unsure of how to do this, you might find this documentation helpful. The Express server that comes with the starter kit is able to be extended to serve as an API and more, but is not required for a static deployment.