diff --git a/docs/FAQ.md b/docs/FAQ.md index 86f43568c..e9bbb25b7 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -48,11 +48,11 @@ --- -###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** | @@ -72,7 +72,7 @@ Unfortunately, scripts in package.json can't be commented inline because the JSO | 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? ``` . ├── .babelrc # Configures Babel @@ -114,7 +114,7 @@ Unfortunately, scripts in package.json can't be commented inline because the JSO ``` -### 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. | @@ -174,15 +174,15 @@ Unfortunately, scripts in package.json can't be commented inline because the JSO |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`: @@ -202,11 +202,11 @@ 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` @@ -214,7 +214,7 @@ This starter kit includes an example app so you can see how everything hangs tog 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` @@ -223,7 +223,7 @@ Nope. Redux is useful for applications with more complex data flows. If your app 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` 2. Delete the following files: `src/routes.js` 3. Remove `import { Link, IndexLink } from 'react-router';` from top of `src/components/App.js`, add a reference to `src/components/FuelSavingsForm.js`, and replace body of (implicit) render with this: ``. @@ -236,7 +236,7 @@ Nope. Redux is useful for applications with more complex data flows. If your app * Places the resulting built project files into /dist. (This is the folder you'll expose to the world). -### Why are test files placed alongside the file under test (instead of centralized)? +### 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. @@ -247,7 +247,7 @@ Streamlined automated testing is a core feature of this starter kit. All tests a That said, you can of course place your tests under __test__ instead. Then Jest will simply look in /test to find your spec files. -### How do I debug? +### 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](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) 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 above](https://github.com/coryhouse/react-slingshot/blob/master/docs/FAQ.md#how-do-i-deploy-this). @@ -260,22 +260,22 @@ Also note that no actual physical files are written to the filesystem during the 3. 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. -#### Debugging in Visual Studio Code: +#### Debugging in Visual Studio Code: * Install the [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome) extension. * Follow the instructions on how to [configure debugging in Visual Studio code](https://github.com/Microsoft/vscode-chrome-debug/blob/master/README.md#using-the-debugger). Don't see your favorite code editor debugging configuration here? Submit a PR and we'll be glad to add it to the FAQ.md. -### Why does the build use npm scripts instead of Gulp or Grunt? +### Why does the build use npm scripts instead of Gulp or Grunt? In short, Gulp is an unnecessary abstraction that creates more problems than it solves. [Here's why](https://medium.com/@housecor/why-i-left-gulp-and-grunt-for-npm-scripts-3d6853dd22b8#.vtaziro8n). -### Why does package.json reference the exact version? +### Why does package.json reference the exact version? This assures that the build won't break when some new version is released. Unfortunately, many package authors don't properly honor [Semantic Versioning](http://semver.org), so instead, as new versions are released, we'll test them and then introduce them into React Slingshot. But yes, this means when you do `npm update` no new dependencies will be pulled down. You'll have to update package.json with the new version manually. -### How do I handle images? +### How do I handle images? Via Webpack's file loader. Example: ``` @@ -286,19 +286,19 @@ Via Webpack's file loader. Webpack will then intelligently handle your image for you. For the production build, it will copy the physical file to /dist, give it a unique filename, and insert the appropriate path in your image tag. -### I'm getting an error when running npm install: Failed to locate "CL.exe" +### 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 +### 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. Alternatively, you can use a tool like [localtunnel](https://localtunnel.github.io/www/) or [ngrok](https://ngrok.com) to expose your app via a public URL. This way, you can interact with the Browsersync hosted app on any device. -### What about the Redux Devtools? +### What about the Redux Devtools? Install the [Redux devtools extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en) in Chrome Developer Tools. If you're interested in running Redux dev tools cross-browser, Barry Staes created a [branch with the devtools incorporated](https://github.com/coryhouse/react-slingshot/pull/27). -### Hot reloading isn't working! +### Hot reloading isn't working! Hot reloading doesn't always play nicely with stateless functional components at this time. [This is a known limitation that is currently being worked](https://github.com/gaearon/babel-plugin-react-transform/issues/57). To avoid issues with hot reloading for now, use a traditional class-based React component at the top of your component hierarchy. @@ -319,8 +319,5 @@ That's it! Travis will now execute the `npm run test:cover:travis` script after You can get the badge from the Coveralls website. -###What about TypeScript? -Here's a [fork with TS support](https://github.com/typescriptcrew/ts-react-slingshot): - - - +### What about TypeScript? +Here's a [fork with TS support](https://github.com/typescriptcrew/ts-react-slingshot).