|
1 | | -# skeleton-ui-react |
| 1 | +# React Starter Project |
| 2 | + |
| 3 | +## Acknowledgements |
| 4 | + |
| 5 | +This is a [LEAN**STACKS**](https://leanstacks.com/) solution. |
| 6 | + |
| 7 | +## Getting Started |
| 8 | + |
| 9 | +This is a Single-Page Application (SPA) user interface application authored in JavaScript using the [React](https://reactjs.org/) framework. |
| 10 | + |
| 11 | +## Languages |
| 12 | + |
| 13 | +This project is primarily authored in: |
| 14 | + |
| 15 | +* ECMAScript 2017 (JavaScript 8th Edition) with syntatic sugar via Babel |
| 16 | +* HTML |
| 17 | +* SASS |
| 18 | + |
| 19 | +**Note:** Babel allows developers the flexibility to choose the 6th, 7th, or 8th edition of JavaScript. The Babel transpiler ensures a browser-compatible build. |
| 20 | + |
| 21 | +## Installation |
| 22 | + |
| 23 | +### Fork the Repository |
| 24 | + |
| 25 | +Fork the [GitHub repo](https://github.com/leanstacks/skeleton-ui-react). Clone the project to the host machine. |
| 26 | + |
| 27 | +### Dependencies |
| 28 | + |
| 29 | +This project requires the following global dependencies on the host machine: |
| 30 | + |
| 31 | +* Node 6+ |
| 32 | +* NPM 3+ |
| 33 | +* Yarn 1.3+ |
| 34 | + |
| 35 | +**Note:** This project has been tested with Node 8.11+ (Carbon) and 6.14+ (Boron). |
| 36 | + |
| 37 | +After installing the global dependencies, initialize the project. Open a terminal window, navigate to the project base directory and issue this command: |
| 38 | + |
| 39 | +``` |
| 40 | +yarn install |
| 41 | +``` |
| 42 | + |
| 43 | +Yarn retrieves all project dependencies and installs them into the `/node_modules` sub-directory. |
| 44 | + |
| 45 | +### Editors |
| 46 | + |
| 47 | +You may use your preferred text editor. [Atom](https://atom.io/) or [VS Code](https://code.visualstudio.com/) are recommended. |
| 48 | + |
| 49 | +## Running |
| 50 | + |
| 51 | +The project uses [Yarn commands](https://yarnpkg.com/lang/en/docs/cli/) for build, test, and local debugging workflow automation. The following Yarn commands are defined. |
| 52 | + |
| 53 | +### Start |
| 54 | + |
| 55 | +The **start** command performs the following workflow steps: |
| 56 | + |
| 57 | +* starts the Webpack development server |
| 58 | +* builds the application and loads it into memory |
| 59 | +* watches source directories for changes |
| 60 | +* republishes source files when changes occur |
| 61 | +* reloads the application in the browser when changed source files are republished |
| 62 | + |
| 63 | +The **start** command is designed to allow engineers the means to rapidly make application changes on their local machines. This task is not intended for use in a server environment. |
| 64 | + |
| 65 | +To execute the **start** command, type the following at a terminal prompt in the project base directory: |
| 66 | + |
| 67 | +``` |
| 68 | +yarn start |
| 69 | +``` |
| 70 | + |
| 71 | +Open a browser and go to http://localhost:9000/ to use the application. |
| 72 | + |
| 73 | +To stop the Webpack development server, press `ctrl-C` in the terminal window. |
| 74 | + |
| 75 | +### Test |
| 76 | + |
| 77 | +The **test** command performs the following workflow steps: |
| 78 | + |
| 79 | +* executes tests once and exits |
| 80 | + |
| 81 | +The **test** command is designed to allow engineers the means to run all tests contained within `*.test.js` files located in the `/src/tests/` sub-directory. |
| 82 | + |
| 83 | +To execute the **test** command, type the following at a terminal prompt in the project base directory: |
| 84 | + |
| 85 | +``` |
| 86 | +yarn test |
| 87 | +``` |
| 88 | + |
| 89 | +To start the test environment and re-execute tests as source files are modified, use the `--watch` option. |
| 90 | + |
| 91 | +``` |
| 92 | +yarn test --watch |
| 93 | +``` |
| 94 | + |
| 95 | +To stop the test environment in watch mode, press `q` in the terminal window. |
| 96 | + |
| 97 | +### Build |
| 98 | + |
| 99 | +The **build** command performs the following workflow steps: |
| 100 | + |
| 101 | +* starts the Webpack process |
| 102 | +* creates a clean distribution `/dist` directory |
| 103 | +* copies all static assets to the distribution directory |
| 104 | +* transpiles, ugilifies, minifies, and maps source files into distribution bundles |
| 105 | +* injects the distribution bundles into `link` and `script` tags within the `index.html` file |
| 106 | + |
| 107 | +To execute the **build** command, type the following at a terminal prompt in the project base directory: |
| 108 | + |
| 109 | +``` |
| 110 | +yarn build |
| 111 | +``` |
| 112 | + |
| 113 | +The **build** command has environment-specific variants which allow for the injection of alternative values into environment variables via the [Webpack Define Plugin](https://webpack.js.org/plugins/define-plugin/). See the Define Plugin documentation for more information. |
| 114 | + |
| 115 | +To execute the **build** command for a configured environment, type the following command at a terminal prompt in the base directory: |
| 116 | + |
| 117 | +``` |
| 118 | +yarn build:dev |
| 119 | +
|
| 120 | +OR |
| 121 | +
|
| 122 | +yarn build:qa |
| 123 | +``` |
| 124 | + |
| 125 | +## Deployment |
| 126 | + |
| 127 | +This project is ideally suited to be hosted from a static web server (e.g. Apache or Nginx) or from a CDN (e.g. AWS CloudFront). |
| 128 | + |
| 129 | +To prepare the application distribution for deployment, run the **build** Yarn command documented above. Next, take all of the files and directories from the `/dist` directory and deploy them to your hosting environment. |
| 130 | + |
| 131 | +### Web Server Configuration |
| 132 | + |
| 133 | +#### Fallback to index.html |
| 134 | + |
| 135 | +Routed applications must fall back to `index.html`. That means, if you are using SPA routing you must configure the static web server to return to the base html page (`index.html`) when the router is asked to serve a route which does not exist. |
| 136 | + |
| 137 | +A static web server commonly returns `index.html` when it receives a request for `http://www.example.com/`. But it returns a `404 - Not Found` error when processing `http://www.example.com/greetings/109` unless it is configured to return `index.html` instead. |
| 138 | + |
| 139 | +Each static web server is configured for fallback in a different way. Here are a few examples for common scenarios. |
| 140 | + |
| 141 | +##### Webpack Development Server |
| 142 | + |
| 143 | +``` |
| 144 | +historyApiFallback: { |
| 145 | + disableDotRule: true, |
| 146 | + htmlAcceptHeaders: [text/html', 'application/xhtml+xml'] |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +##### Apache |
| 151 | + |
| 152 | +Add a rewrite rule to the `.htaccess` file as illustrated below. |
| 153 | + |
| 154 | +``` |
| 155 | +RewriteEngine On |
| 156 | + # If an existing asset or directory is requested, go to it as it is |
| 157 | + RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR] |
| 158 | + RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d |
| 159 | + RewriteRule ^ - [L] |
| 160 | + # If the requested resource doesn't exist, use index.html |
| 161 | + RewriteRule ^ /index.html |
| 162 | +``` |
| 163 | + |
| 164 | +##### NGinx |
| 165 | + |
| 166 | +Use `try_files` as described in the [Front Controller Pattern Web Apps](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#front-controller-pattern-web-apps) documentation. |
| 167 | + |
| 168 | +``` |
| 169 | +try_files $uri $uri/ /index.html; |
| 170 | +``` |
| 171 | + |
| 172 | +##### IIS |
| 173 | + |
| 174 | +Add a rewrite rule to `web.config`, similar to the one illustrated below. |
| 175 | + |
| 176 | +``` |
| 177 | +<system.webServer> |
| 178 | + <rewrite> |
| 179 | + <rules> |
| 180 | + <rule name="Angular Routes" stopProcessing="true"> |
| 181 | + <match url=".*" /> |
| 182 | + <conditions logicalGrouping="MatchAll"> |
| 183 | + <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> |
| 184 | + <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> |
| 185 | + </conditions> |
| 186 | + <action type="Rewrite" url="/src/" /> |
| 187 | + </rule> |
| 188 | + </rules> |
| 189 | + </rewrite> |
| 190 | +</system.webServer> |
| 191 | +``` |
| 192 | + |
| 193 | +## Technology Stacks |
| 194 | + |
| 195 | +### Application |
| 196 | + |
| 197 | +[React](https://reactjs.org/) |
| 198 | +[Redux](https://redux.js.org/) |
| 199 | +[React Router](https://reacttraining.com/react-router/) |
| 200 | +[Axios](https://github.com/axios/axios) |
| 201 | +[Lodash](https://lodash.com/) |
| 202 | +[Moment](https://momentjs.com/) |
| 203 | +[Numeral](http://numeraljs.com/) |
| 204 | +[Bootstrap](https://getbootstrap.com/) |
| 205 | +[Font Awesome](https://fontawesome.com/) |
| 206 | +[Google Fonts](https://fonts.google.com) |
| 207 | +[JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) |
| 208 | +[SASS](http://sass-lang.com/guide) |
| 209 | + |
| 210 | +### Test |
| 211 | + |
| 212 | +[Jest](http://jestjs.io/) |
| 213 | +[Enzyme](http://airbnb.io/enzyme/) |
| 214 | +[Redux Mock Store](https://www.npmjs.com/package/redux-mock-store) |
| 215 | + |
| 216 | +### Build |
| 217 | + |
| 218 | +[Babel](http://babeljs.io/) |
| 219 | +[Node.js](https://nodejs.org/) |
| 220 | +[Webpack](https://webpack.js.org/configuration/) |
| 221 | +[Yarn](https://yarnpkg.com/en/) |
0 commit comments