diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ddc88e0d..0ee6e25c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,17 +1,22 @@ # Contributing ## Quick Start + Fork this project, then: -``` + +```bash npm install npm start ``` + Submit a pull request to the master branch to request merging your change. ## Branch Organization + All features should be worked out of a well named feature branch. Branch off the master branch. Submit a pull request to merge your work into the master branch when your work is ready for review. ## npm Scripts + This project uses npm scripts for automation |Script|Description| @@ -22,17 +27,21 @@ This project uses npm scripts for automation There are many other scripts in package.json, but these are the two you're most likely to run. ## Semantic Versioning + This project follows [semantic versioning](http://semver.org). We release patch versions for bugfixes, minor versions for new features, and major versions for any breaking changes. ## Proposing a Change + If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it. ## Style Guide + ESLint will catch most styling issues that may exist in your code. You can check the status of your code styling by running npm start. However, there are still some styles that the linter cannot pick up. If you are unsure about something, looking at [Airbnb's Style Guide](https://github.com/airbnb/javascript) will guide you in the right direction. ## Code Conventions + - Use semicolons ; - 2 spaces for indentation (no tabs). Install the [Editorconfig](http://editorconfig.org) plugin for your editor to enforce this automatically. - Prefer ' over " diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 515f8b911..e489cadff 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,5 +1,9 @@ -react-slingshot contributors (sorted alphabetically) -==================================================== +# contributors + +## react-slingshot + +--- + * Atif Afzal ([atfzl](https://github.com/atfzl)) * Andrew Murray ([radarhere](https://github.com/radarhere)) * Barry Staes ([barrystaes](https://github.com/barrystaes)) diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index 4f31b6652..60317379e 100644 --- a/PULL_REQUEST_TEMPLATE.md +++ b/PULL_REQUEST_TEMPLATE.md @@ -1,11 +1,11 @@ +# Pull Request Template + The code review checklist below is used for all pull requests. 1. Review the list before submitting your pull request. 2. Leave the list intact for the code reviewer's use. -Thanks! :) - -## Code Review Checklist +## Checklist - [ ] Latest code from master has been merged into the pull request branch - [ ] Honors [the seven code virtues](https://pragprog.com/magazines/2011-08/how-virtuous-is-your-code) @@ -22,3 +22,7 @@ Thanks! :) - [ ] Automated tests exist and pass - [ ] Build is successful (`npm run build`) - [ ] Works in IE 11, Chrome, Firefox, and Edge + +## Thanks! + +:heart: diff --git a/README.md b/README.md index dcc746b0d..7ccafa3fd 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ -
++ +
+ +--- [![Build status: Linux](https://img.shields.io/travis/coryhouse/react-slingshot.svg?style=flat-square)](https://travis-ci.org/coryhouse/react-slingshot) [![Build status: Windows](https://img.shields.io/appveyor/ci/coryhouse/react-slingshot/master.svg?style=flat-square)](https://ci.appveyor.com/project/coryhouse/react-slingshot/branch/master) [![Dependency Status](https://david-dm.org/coryhouse/react-slingshot.svg?style=flat-square)](https://david-dm.org/coryhouse/react-slingshot) [![Coverage Status](https://img.shields.io/coveralls/coryhouse/react-slingshot/master.svg?style=flat-square)](https://coveralls.io/github/coryhouse/react-slingshot?branch=master) -A comprehensive starter kit for rapid application development using React. +A comprehensive starter kit for rapid application development using React. Why Slingshot? @@ -18,36 +22,71 @@ Why Slingshot? [![React Slingshot Production Build](https://img.youtube.com/vi/qlfDLsX-J0U/0.jpg)](https://www.youtube.com/watch?v=qlfDLsX-J0U) -## Get Started +# Get Started + +1. **Initial Machine Setup** + + First time running the starter kit? Then complete the [Initial Machine Setup](#initial-machine-setup). + +2. **Clone the project** + + `git clone https://github.com/coryhouse/react-slingshot.git`. + +3. **Run the setup script** + + `npm run setup` + +4. **Run the example app** -1. **Initial Machine Setup**. First time running the starter kit? Then complete the [Initial Machine Setup](https://github.com/coryhouse/react-slingshot#initial-machine-setup). -2. **Clone the project**. `git clone https://github.com/coryhouse/react-slingshot.git`. -3. **Run the setup script**. `npm run setup` -4. **Run the example app**. `npm start -s` -This will run the automated build process, start up a webserver, and open the application in your default browser. When doing development with this kit, this command will continue watching all your files. Every time you hit save the code is rebuilt, linting runs, and tests run automatically. Note: The -s flag is optional. It enables silent mode which suppresses unnecessary messages during the build. -5. **Review the example app.** This starter kit includes a working example app that calculates fuel savings. Note how all source code is placed under /src. Tests are placed alongside the file under test. The final built app is placed under /dist. These are the files you run in production. -6. **Delete the example app files.** Once you're comfortable with how the example app works, you can [delete those files and begin creating your own app](https://github.com/coryhouse/react-slingshot/blob/master/docs/FAQ.md#i-just-want-an-empty-starter-kit). -7. **Having issues?** See "Having Issues?" below. + `npm start -s` + + This will run the automated build process, start up a webserver, and open the application in your default browser. When doing development with this kit, this command will continue watching all your files. Every time you hit save the code is rebuilt, linting runs, and tests run automatically. Note: The -s flag is optional. It enables silent mode which suppresses unnecessary messages during the build. + +5. **Review the example app.** + + This starter kit includes a working example app that calculates fuel savings. Note how all source code is placed under /src. Tests are placed alongside the file under test. The final built app is placed under /dist. These are the files you run in production. + +6. **Delete the example app files.** + + Once you're comfortable with how the example app works, you can [delete those files and begin creating your own app](./docs/FAQ.md#i-just-want-an-empty-starter-kit). + +7. **Having issues?** See [Having Issues?](#having-issues-try-these-things-first). ## Initial Machine Setup -1. **Install [Node 4.0.0 or greater](https://nodejs.org)** - (5.0 or greater is recommended for optimal build performance). Need to run multiple versions of Node? Use [nvm](https://github.com/creationix/nvm). -2. **Install [Git](https://git-scm.com/downloads)**. +1. **Install [Node 4.0.0 or greater](https://nodejs.org)** + + (5.0 or greater is recommended for optimal build performance) + Need to run multiple versions of Node? Use [nvm](https://github.com/creationix/nvm). + +2. **Install [Git](https://git-scm.com/downloads)**. + 3. **[Disable safe write in your editor](https://webpack.js.org/guides/development/#adjusting-your-text-editor)** to assure hot reloading works properly. -4. On a Mac? You're all set. If you're on Linux or Windows, complete the steps for your OS below. - -**On Linux:** - * Run this to [increase the limit](http://stackoverflow.com/questions/16748737/grunt-watch-error-waiting-fatal-error-watch-enospc) on the number of files Linux will watch. [Here's why](https://github.com/coryhouse/react-slingshot/issues/6). -`echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p` +4. On a Mac? You're all set. If you're on Linux or Windows, complete the steps for your OS below. + + ### On Linux + + * Run this to [increase the limit](http://stackoverflow.com/questions/16748737/grunt-watch-error-waiting-fatal-error-watch-enospc) on the number of files Linux will watch. [Here's why](https://github.com/coryhouse/react-slingshot/issues/6). -**On Windows:** - -* **Install [Python 2.7](https://www.python.org/downloads/)**. Some node modules may rely on node-gyp, which requires Python on Windows. -* **Install C++ Compiler**. Browser-sync requires a C++ compiler on Windows. [Visual Studio Express](https://www.visualstudio.com/en-US/products/visual-studio-express-vs) comes bundled with a free C++ compiler. Or, if you already have Visual Studio installed: Open Visual Studio and go to File -> New -> Project -> Visual C++ -> Install Visual C++ Tools for Windows Desktop. The C++ compiler is used to compile browser-sync (and perhaps other Node modules). + `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`. -## Having Issues? Try these things first. -1. Make sure you ran all steps in [Get started](https://github.com/coryhouse/react-slingshot/blob/master/README.md#get-started) including the [initial machine setup](https://github.com/coryhouse/react-slingshot#initial-machine-setup). + ### On Windows + + * **Install [Python 2.7](https://www.python.org/downloads/)**. Some node modules may rely on node-gyp, which requires Python on Windows. + * **Install C++ Compiler**. Browser-sync requires a C++ compiler on Windows. + + [Visual Studio Express](https://www.visualstudio.com/en-US/products/visual-studio-express-vs) comes bundled with a free C++ compiler. + + If you already have Visual Studio installed: + Open Visual Studio and go to File -> New -> Project -> Visual C++ -> Install Visual C++ Tools for Windows Desktop. + The C++ compiler is used to compile browser-sync (and perhaps other Node modules). + +--- + +## Having Issues? Try these things first + +1. Make sure you ran all steps in [Get started](#get-started) including the [initial machine setup](#initial-machine-setup). 2. Run `npm install` - If you forget to do this, you'll see this: `babel-node: command not found`. 3. Install the latest version of Node. Or install [Node 5.12.0](https://nodejs.org/download/release/v5.12.0/) if you're having issues on Windows. Node 6 has issues on some Windows machines. 4. Make sure files with names that begin with a dot (.editorconfig, .gitignore, .npmrc) are copied to the project directory root. This is easy to overlook if you copy this repository manually. @@ -55,30 +94,33 @@ This will run the automated build process, start up a webserver, and open the ap 6. Delete any .eslintrc that you're storing in your user directory. Also, disable any ESLint plugin / custom rules that you've enabled within your editor. These will conflict with the ESLint rules defined in this project. 7. Make sure you don't have NODE_ENV set to production on your machine. If you do then the [development dependencies won't be installed](https://github.com/coryhouse/react-slingshot/issues/400#issuecomment-290497767). Here's [how to check](http://stackoverflow.com/a/27939821/26180). 8. Install watchman with `brew install watchman` if you are having the following error after an initial `npm start -s`: -```sh -2017-09-05 00:44 node[68587] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22) -2017-09-05 00:44 node[68587] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22) -events.js:160 - throw er; // Unhandled 'error' event - ^ - -Error: Error watching file for changes: EMFILE - at exports._errnoException (util.js:1022:11) - at FSEvent.FSWatcher._handle.onchange (fs.js:1406:11) -``` + + ```bash + 2017-09-05 00:44 node[68587] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22) + 2017-09-05 00:44 node[68587] (FSEvents.framework) FSEventStreamStart: register_with_server: ERROR: f2d_register_rpc() => (null) (-22) + events.js:160 + throw er; // Unhandled 'error' event + ^ + + Error: Error watching file for changes: EMFILE + at exports._errnoException (util.js:1022:11) + at FSEvent.FSWatcher._handle.onchange (fs.js:1406:11) + ``` + 9. Tip: Things to check if you get an `npm run lint` error or build error: - * If ESW found an error or warning in your project (e.g. console statement or a missing semi-colon), the lint thread will exit with `Exit status 1`. To fix: + * If ESW found an error or warning in your project (e.g. console statement or a missing semi-colon), the lint thread will exit with `Exit status 1`. To fix: 1. Change the `npm run lint` script to `"esw webpack.config.* src tools; exit 0"` 1. Change the `npm run lint:watch` script to `"esw webpack.config.* src tools --watch; exit 0"` > Note: Adding `exit 0` will allow the npm scripts to ignore the status 1 and allow ESW to print all warnings and errors. - * Ensure the `eslint`/`esw` globally installed version matches the version used in the project. This will ensure the `esw` keyword is resolved. + 10. Rebuild node-sass with `npm rebuild node-sass` if you are having and error like `Node Sass does not yet support your current environment on macOS XXX` after an initial `npm start -s`. - +--- + ## Technologies Slingshot offers a rich development experience using the following technologies: @@ -100,5 +142,9 @@ Slingshot offers a rich development experience using the following technologies: | [npm Scripts](https://docs.npmjs.com/misc/scripts)| Glues all this together in a handy automated build. | [Pluralsight course](https://www.pluralsight.com/courses/npm-build-tool-introduction), [Why not Gulp?](https://medium.com/@housecor/why-i-left-gulp-and-grunt-for-npm-scripts-3d6853dd22b8#.vtaziro8n) | The starter kit includes a working example app that puts all of the above to use. + +--- + ## Questions? -Check out the [FAQ](/docs/FAQ.md) + +Check out the [FAQ](./docs/FAQ.md) diff --git a/docs/FAQ.md b/docs/FAQ.md index 9ea4b9699..16b735bc0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,15 +1,16 @@ -## FAQ +# FAQ + [Why does this exist?](#why-does-this-exist) -[What do the scripts in package.json do?](#what-do-the-scripts-in-package.json-do) +[What do the scripts in package.json do?](#what-do-the-scripts-in-packagejson-do) [Can you explain the folder structure?](#can-you-explain-the-folder-structure) -[What are the dependencies in package.json used for?](#what-are-the-dependencies-in-package.json-used-for) +[What are the dependencies in package.json used for?](#what-are-the-dependencies-in-packagejson-used-for) [Where are the files being served from when I run `npm start`?](#where-are-the-files-being-served-from-when-i-run-npm-start) -[Where is index.html?](#where-is-index.html) +[Where is index.html?](#where-is-indexhtml) [How is Sass being converted into CSS and landing in the browser?](#how-is-sass-being-converted-into-css-and-landing-in-the-browser) @@ -47,12 +48,12 @@ --- - -### Why does this exist? +## Why does this exist? + This starter kit implements best practices like testing, minification, bundling, and so on. It codifies a long list of decisions that you no longer have to make to get rolling. It saves you from the long, painful process of wiring it all together into an automated dev environment and build process. It's also useful as inspiration for ideas you might want to integrate into your current development environment or build process. - -### What do the scripts in package.json do? +## What do the scripts in package.json do? + Unfortunately, scripts in package.json can't be commented inline because the JSON spec doesn't support comments, so I'm providing info on what each script in package.json does here. | **Script** | **Description** | @@ -71,9 +72,9 @@ Unfortunately, scripts in package.json can't be commented inline because the JSO | test:cover:travis | Runs coverage as described above, however sends machine readable lcov data to Coveralls. This should only be used from the travis build! | | analyze-bundle | Analyzes webpack bundles for production and gives you a breakdown of where modules are used and their sizes via a convenient interactive zoomable treemap. | - -### Can you explain the folder structure? -``` +## Can you explain the folder structure? + +```bash . ├── .editorconfig # Configures editor rules ├── .gitignore # Tells git which files to ignore @@ -111,8 +112,8 @@ Unfortunately, scripts in package.json can't be commented inline because the JSO └── webpack.config.prod.js # Configures webpack for production builds ``` - -### What are the dependencies in package.json used for? +## What are the dependencies in package.json used for? + | **Dependency** | **Use** | |----------|-------| |autoprefixer | Automatically adds vendor prefixes, using data from Can I Use. | @@ -171,16 +172,16 @@ Unfortunately, scripts in package.json can't be commented inline because the JSO |webpack-hot-middleware| Use to integrate Webpack's hot reloading support with Browser-sync | |webpack-md5-hash| Hash bundles, and use the hash for the filename so that the filename only changes when contents change| - -### Where are the files being served from when I run `npm start`? +## Where are the files being served from when I run `npm start`? + Webpack serves your app in memory when you run `npm start`. No physical files are written. However, the web root is /src, so you can reference files under /src in index.html. When the app is built using `npm run build`, physical files are written to /dist and the app is served from /dist. - -### Where is index.html? +## Where is index.html? + It's generated by webpack using htmlWebpackPlugin. This plugin dynamically generates index.html based on the configuration in webpack.config. It also adds references to the JS and CSS bundles using hash-based filenames to bust cache. Separate bundles for vendor and application code are created and referencing within the generated index.html file so that vendor libraries and app code can be cached separately by the browser. The bundle filenames are based on the file's hash, so the filenames only change when the file contents change. For more information on this, read [Long-term caching of static assets with Webpack](https://medium.com/@okonetchnikov/long-term-caching-of-static-assets-with-webpack-1ecb139adb95#.4aeatmtfz) and [html-webpack-plugin](https://github.com/ampedandwired/html-webpack-plugin) - -### How is Sass being converted into CSS and landing in the browser? +## How is Sass being converted into CSS and landing in the browser? + Magic! Okay, more specifically, we're handling it differently in dev (`npm start`) vs prod (`npm run build`) When you run `npm start`: @@ -199,20 +200,20 @@ When you run `npm run build`: For both of the above methods, a separate sourcemap is generated for debugging Sass in [compatible browsers](http://thesassway.com/intermediate/using-source-maps-with-sass). - -### I don't like the magic you just described above. I simply want to use a CSS file. +## I don't like the magic you just described above. I simply want to use a CSS file. + No problem. Reference your CSS file in index.html, and add a step to the build process to copy your CSS file over to the same relative location /dist as part of the build step. But be forwarned, you lose style hot reloading with this approach. - -### I just want an empty starter kit. +## I just want an empty starter kit. + This starter kit includes an example app so you can see how everything hangs together on a real app. When you're done reviewing it, run this to remove the demo app: `npm run remove-demo` Don't want to use Redux? See the next question for some steps on removing Redux. - -### Do I have to use Redux? +## Do I have to use Redux? + Nope. Redux is useful for applications with more complex data flows. If your app is simple, Redux is overkill. Remove Redux like this: 1. Run `npm run remove-demo` @@ -220,13 +221,12 @@ Nope. Redux is useful for applications with more complex data flows. If your app 3. Create a new empty component in /components. 4. Call render on the new top level component you created in step 3 in src/index.js. - -### How do I remove React Router? +## How do I remove React Router? + 1. Uninstall React Router and routing related packages: `npm uninstall --save react-router-dom` 2. Remove `import { Switch, NavLink, Route } from 'react-router-dom';` from top of `src/components/App.js`, add a reference to `src/components/FuelSavingsForm.js`, and replace body of (implicit) render with this: `