docs(docs/*): add some new docs

Metnew · Aug 9, 2017 · 8e1eec3 · 8e1eec3
1 parent 9615094
commit 8e1eec3
Show file tree

Hide file tree

Showing 8 changed files with 107 additions and 22 deletions.
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
diff --git a/docs/SUI.md b/docs/SUI.md
@@ -0,0 +1,43 @@
+# Semantic.UI & React
+
+Semantic-UI-React is a great choice, almost a great choice.
+
+> SUI = Semantic.UI        
+SUIR = Semantic-UI-React
+
+### No SUIR?
+You can always select another framework - [my article with comparison of best React UI frameworks.](https://hackernoon.com/the-coolest-react-ui-frameworks-for-your-new-react-app-ad699fffd651)    
+If you still don't want to use SUIR, just remove it from the boilerplate. The boilerplate is great even without Semantic.
+
+## SUIR
+
+### Good parts:
+##### 1. Big UI library:
+There are many great components that are ready to use. It's probably the biggest and most full-featured React UI framework.
+##### 2. Based on SUI:
+When you use SUIR you import all SUI styles. So you can use the power of SUI that already has a very big community, many components/utils/plugins/etc.
+
+### Bad parts:
+There are few issues using SUIR:
+
+##### 1. SUIR use css styles:
+SUIR is build based on [`classnames`](https://github.com/JedWatson/classnames) and CSS styles from SUI. According to the [issues and proposals](https://github.com/Semantic-Org/Semantic-UI-React/issues/1009) in SUIR repo, SUIR will migrate to inline-styles library like `radium`, `styled-components`, `glamour`.
+
+The main problems of using SUI CSS styles:
+  1. SSR can't render all the things.
+  2. Import of unused styles. Using library like `styled-components` we import only styles that are used.
+  > You can try to use PurifyCss to remove unused css. But probably it doesn't help, because PurifyCss determinate unused styles based only on static markup.
+  3. SUI styles are huge and blocks rendering.
+  <img src="./assets/sui-block.png" />
+  > There is a trick for this: you can split SUI styles into 2 smaller chunks that would be downloaded faster, if you use HTTP2.
+
+
+#### 2. Lodash is a dependency of SUIR:
+Lodash is great, but probably it isn't always needed in small projects. Not sure that's a real issue, because almost every middle/big size project uses Lodash.
+
+#### 3. Still lacks some specific omponents.
+Like `<Calendar />` and `<Datepicker />`. [But they'll appear soon.](https://github.com/Semantic-Org/Semantic-UI-React/pull/1240) That's probably not an issue at all, because SUIR already has many components and you can use other libraries for specific tasks. For example, [`react-dates`](https://github.com/airbnb/react-dates) for full-featured Calendar component.
+
+### Summary
+SUIR is great, but it still lacks inline-styles. If this feature would be added soon, than SUIR probably will be the best React framework.
+> Every contribution in [SUIR](https://react.semantic-ui.com/introduction) is highly appreciated :)
diff --git a/docs/auth.md b/docs/auth.md
diff --git a/docs/design.md b/docs/design.md
@@ -0,0 +1,4 @@
+# Starter design
+
+The main purpose of this starter:
+Create app skeleton that already has all commonly used features and still stays flexible.
diff --git a/docs/env_vars.md b/docs/env_vars.md
@@ -2,7 +2,8 @@
 
 > if you don't know what is environment variables - [this link is for you](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps)
 
-Environment variables are very important for configuration.
+Environment variables are very important for configuration. Some variables are used for webpack configuration, other variables are used in code (using `webpack.DefinePlugin`).
+
 ## Frontend
 
 #### `GA_ID (default:false)`:
@@ -29,19 +30,38 @@ if (process.env.GA_ID) {
 }
 ```
 ##### Why not to add GA in index.html?
-Because, if GA is added only after `DOMContentLoaded`, it saves page loading time.
+Because, it saves loading time.
 
 #### `SENTRY_PUBLIC_DSN (default: false)`:
 Similar to `GA_ID`, but for [Sentry](https://sentry.io).
 
 #### `BASE_API (default: '/api/v1')`:
-App uses this path for requests with relative urls
+This is the prefix of your server API. This prefix is used by both client and server.    
+Server inits API based on this prefix in `src/server/server.js`:
+```js
+// ...
+const {BASE_API, PORT} = process.env
+// Add API route
+app.use(BASE_API, API)
+// ...
+```
 
-#### `APP_LANGUAGE (default: 'en')`:
-Build app with this language. Check `/i18n` folder and **[i18n-webpack-plugin](https://github.com/webpack-contrib/i18n-webpack-plugin)**.  
+Client makes all requests to server using this prefix:
+```js
+// ...
+// Check that req url is relative and request was sent to our domain
+if (url.match(/^https?:\/\//gi) > -1) {
+  const token = getLocalToken()
+  if (token) {
+    defaults.headers.Authorization = `JWT ${token}`
+  }
+  url = process.env.BASE_API + url
+}
+// ...
+```
 
-#### `ANALYZE_BUNDLE (default: false)`:   
-Run [webpack-bundle-analyzer]() after build.    
+#### `APP_LANGUAGE (default: 'en')`:
+Variable is used by webpack for build configuration, but you still have access to it in code. It might be useful to know app language for simple localization or other tasks.
 
 ## Server:
 

diff --git a/docs/ssr.md b/docs/ssr.md
diff --git a/docs/testing.md b/docs/testing.md
@@ -2,12 +2,14 @@
 
 ## Jest
 
-Starter uses Jest for testing.
+The boilerplate uses Jest for testing.
 You can find more about Jest in [official docs](https://facebook.github.io/jest/).
 
 You can run tests using `npm run test` that is an alias to `jest --config=jest_config/jest.config.json --coverage --forceExit || true"`.
 
-Our Jest configuration in `jest_config/jest.config.json` looks like:
+### Configuring Jest
+
+Jest configuration in `jest_config/jest.config.json` looks like:
 ```json
 {
   "moduleFileExtensions": ["js", "jsx"],
@@ -36,8 +38,7 @@ Our Jest configuration in `jest_config/jest.config.json` looks like:
   }
 }
 ```
-Jest doesn't know about webpack aliases, so we have to provide them.
-
+Jest doesn't know about webpack aliases, so we have to provide them.   
 Then we have to provide additional configuration for Jest using `setupFiles` property in Jest config object.
 
 `jest_config/setupJest.js`
@@ -48,7 +49,7 @@ global.fetch = require('node-fetch')
 process.env.BASE_API = process.env.BASE_API || 'http://localhost:4000/api/v1'
 ```
 
-That's all. Jest is configured for using.
+That's all. Jest is ready.
 
 ## How to test React components?
 

diff --git a/docs/webpack.md b/docs/webpack.md
@@ -0,0 +1,27 @@
+# Webpack
+
+## Isomorphism
+Both server and client code are compiled with.
+
+## Frontend
+
+### Development
+
+### Production
+#### `ANALYZE_BUNDLE (default: false)`:   
+Run [webpack-bundle-analyzer]() after production build. Not used for configuration.
+
+#### `APP_LANGUAGE (default: 'en')`:
+Build app with this language. Check `/i18n` folder and **[i18n-webpack-plugin](https://github.com/webpack-contrib/i18n-webpack-plugin)**.  
+
+
+## Server
+
+### Development
+
+### Production
+#### `ANALYZE_BUNDLE (default: false)`:   
+Run [webpack-bundle-analyzer]() after production build. Not used for configuration.
+
+#### `APP_LANGUAGE (default: 'en')`:
+Build app with this language. Check `/i18n` folder and **[i18n-webpack-plugin](https://github.com/webpack-contrib/i18n-webpack-plugin)**.