React Slingshot!
React Slingshot is a comprehensive framework for rapid application development using React. It offers a rich development experience including:
| Tech | Description | Learn More |
|---|---|---|
| React | Fast, composable client-side components. | Pluralsight Course |
| Redux | Enforces unidirectional data flows and immutable, hot reloadable store. Lean alternative to Facebook's Flux. | Tutorial |
| Babel | Compiles ES6 to ES5. Enjoy the new version of JavaScript today. | ES6 REPL, ES6 vs ES5, ES6 Katas, Pluralsight course |
| Webpack | Bundles npm packages and our JS into a single file. Includes hot reloading via react-transform-hmr. | Quick Webpack How-to Pluralsight Course |
| Browsersync | Lightweight development HTTP server that supports synchronized testing and debugging on multiple devices. | Intro vid |
| Mocha | Automated tests with Chai for assertions and Cheerio for DOM testing without a browser using Node. | Pluralsight Course |
| TrackJS | JavaScript error tracking. | Free trial |
| ESLint | Lint JS. Reports syntax and style issues. Using eslint-plugin-react for additional React specific linting rules. | |
| SASS | Compiled CSS styles with variables, functions, and more. | Pluralsight Course |
| Editor Config | Enforce consistent editor settings (spaces vs tabs, etc). | IDE Plugins |
| npm Scripts | Glues all this together in a handy automated build. | Pluralsight course, Why not Gulp? |
The starter kit includes a working example app that puts all of the above to use.
Get Started
- Initial Machine Setup. First time running the starter kit? Then complete the Initial Machine Setup.
- Clone the project.
git clone https://github.com/coryhouse/react-slingshot.git. - Install Node packages.
npm install - 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, you'll want to keep the command line open at all times so that your code is rebuilt and tests run automatically every time you hit save. Note: The -s flag is optional. It enables silent mode which supresses unnecessary messages during the build. - 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.
- 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. You can always refer to this repo for the example app code that you deleted.
##Initial Machine Setup
- Install Node.
- Install Git.
- 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 on the number of files Linux will watch. Here's why.
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
On Windows:
- Install Python 2.7. Browser-sync (and various other Node modules) rely on node-gyp, which requires Python on Windows.
- Install C++ Compiler. Visual Studio Express 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).
##FAQ ###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? 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 |
|---|---|
| prestart | Runs automatically before start. Calls remove-dist script which deletes the dist folder. This helps remind you to run the build script before committing since the dist folder will be deleted if you don't. ;) |
| start | Runs tests, lints, starts dev webserver, and opens the app in your default browser. |
| open | Opens the app in your default browser. |
| lint | Runs ESLint. |
| lint:watch | Runs ESLint and watches all files so that they are automatically linted upon save. |
| clean-dist | Removes everything from the dist folder. |
| remove-dist | Deletes the dist folder. |
| create-dist | Creates the dist folder and the necessary subfolders. |
| build:html | Adds trackJS tracking script and copies to /dist. |
| build:sass | Compiles SASS, minifies, generates sourcemap, and stores in /dist. |
| prebuild | Runs automatically before build script (due to naming convention). Cleans dist folder, builds html, and builds sass. |
| build | Bundles all JavaScript using webpack and writes it to /dist. |
| build:verbose | Same as above, but verbose so you can see all the details happening including warnings. |
| test | Runs tests (files ending in .spec.js) using Mocha and outputs results to the command line. Watches all files so tests are re-run upon save. |
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. To create an empty project, you can delete the following:
- Components in src/components
- Styles in src/styles/styles.scss
- Delete files in src/businessLogic
Don't want to use Redux? See the next question for some steps on removing Redux.
Do I have to use Redux?
Nope. Redux is useful for applications with more complex data flows. If your app is simple, Redux may be overkill. In that case, you can uninstall Redux and delete the following folders:
- actions
- constants
- reducers
- containers
In main.js, reference your top level component (instead of Redux's root container at ./containers/root).
Why are test files placed alongside the file under test (instead of centralized)?
Streamlined automated testing is a core feature of this starter kit. All tests are placed in files that end in .spec.js. Spec files are placed in the same directory as the file under test. Why?
- The existence of tests is highly visible. If a corresponding .spec file hasn't been created, it's obvious.
- Easy to open since they're in the same folder as the file being tested.
- Easy to create new test files when creating new source files.
- Short import paths are easy to type and less brittle.
- As files are moved, it's easy to move tests alongside.
That said, you can of course place your tests under /test instead, which is the Mocha default. If you do, you can simplify the test script to no longer specify the path. Then Mocha will simply look in /test to find your spec files.
How do I debug?
Since browsers don't currently support ES6, we're using Babel to compile our ES6 down to ES5. This means the code that runs in the browser looks different than what we wrote. But good news, a sourcemap is generated to enable easy debugging. This means your original JS source will be displayed in your browser's dev console.
Note: When you run npm start, no JS is minified. Why? Because minifying slows the build. So JS is only minified when you run the npm run build script. See more on building for production below.
Also note that no actual physical files are written to the filesystem during the dev build. For performance, all files exist in memory when served from the webpack server.. Physical files are only written when you run npm run build.
Tips for debugging via sourcemaps:
- Browsers vary in the way they allow you to view the original source. Chrome automatically shows the original source if a sourcemap is available. Safari, in contrast, will display the minified source and you'll have to cmd+click on a given line to be taken to the original source.
- Do not enable serving files from your filesystem in Chrome dev tools. If you do, Chrome (and perhaps other browsers) may not show you the latest version of your code after you make a source code change. Instead you must close the source view tab you were using and reopen it to see the updated source code. It appears Chrome clings to the old sourcemap until you close and reopen the source view tab. To clarify, you don't have to close the actual tab that is displaying the app, just the tab in the console that's displaying the source file that you just changed.
- If the latest source isn't displaying the console, force a refresh. Sometimes Chrome seems to hold onto a previous version of the sourcemap which will cause you to see stale code.
How do I deploy this?
Before committing, type npm run build. This will setup the project for production. It does the following:
- Minifies all JS
- Sets NODE_ENV to prod so that React is built in production mode
- Places the resulting built project files into /dist. (This is the folder you'll expose to the world).
I'm getting an error when running npm install: Failed to locate "CL.exe"
On Windows, you need to install extra dependencies for browser-sync to build and install successfully. Follow the getting started steps above to assure you have the necessary dependencies on your machine.
I can't access the external URL for Browsersync
To hit the external URL, all devices must be on the same LAN. So this may mean your dev machine needs to be on the same Wifi as the mobile devices you're testing.