getting-started.md (6984B)
1 ## Getting Started 2 3 ### Requirements 4 5 * Mac OS X, Windows, or Linux 6 * [Yarn](https://yarnpkg.com/) package + [Node.js](https://nodejs.org/) v6.5 or newer 7 * Text editor or IDE pre-configured with React/JSX/Flow/ESlint ([learn more](./how-to-configure-text-editors.md)) 8 9 ### Directory Layout 10 11 Before you start, take a moment to see how the project structure looks like: 12 13 ``` 14 . 15 ├── /build/ # The folder for compiled output 16 ├── /docs/ # Documentation files for the project 17 ├── /node_modules/ # 3rd-party libraries and utilities 18 ├── /public/ # Static files which are copied into the /build/public folder 19 ├── /src/ # The source code of the application 20 │ ├── /components/ # React components 21 │ ├── /core/ # Core framework and utility functions 22 │ ├── /data/ # GraphQL server schema and data models 23 │ ├── /routes/ # Page/screen components along with the routing information 24 │ ├── /client.js # Client-side startup script 25 │ ├── /config.js # Global application settings 26 │ └── /server.js # Server-side startup script 27 ├── /test/ # Unit and end-to-end tests 28 ├── /tools/ # Build automation scripts and utilities 29 │ ├── /lib/ # Library for utility snippets 30 │ ├── /build.js # Builds the project from source to output (build) folder 31 │ ├── /bundle.js # Bundles the web resources into package(s) through Webpack 32 │ ├── /clean.js # Cleans up the output (build) folder 33 │ ├── /copy.js # Copies static files to output (build) folder 34 │ ├── /deploy.js # Deploys your web application 35 │ ├── /postcss.config.js # Configuration for transforming styles with PostCSS plugins 36 │ ├── /run.js # Helper function for running build automation tasks 37 │ ├── /runServer.js # Launches (or restarts) Node.js server 38 │ ├── /start.js # Launches the development web server with "live reload" 39 │ └── /webpack.config.js # Configurations for client-side and server-side bundles 40 ├── Dockerfile # Commands for building a Docker image for production 41 ├── package.json # The list of 3rd party libraries and utilities 42 └── yarn.lock # Fixed versions of all the dependencies 43 ``` 44 45 **Note**: The current version of RSK does not contain a Flux implementation. 46 It can be easily integrated with any Flux library of your choice. The most 47 commonly used Flux libraries are [Flux](http://facebook.github.io/flux/), 48 [Redux](http://redux.js.org/) and [Relay](http://facebook.github.io/relay/). 49 50 ### Quick Start 51 52 #### 1. Get the latest version 53 54 You can start by cloning the latest version of React Starter Kit (RSK) on your 55 local machine by running: 56 57 ```shell 58 $ git clone -o react-starter-kit -b master --single-branch \ 59 https://github.com/kriasoft/react-starter-kit.git MyApp 60 $ cd MyApp 61 ``` 62 63 Alternatively, you can start a new project based on RSK right from 64 [WebStorm IDE](https://www.jetbrains.com/webstorm/help/create-new-project-react-starter-kit.html), 65 or by using [Yeoman generator](https://www.npmjs.com/package/generator-react-fullstack). 66 67 #### 2. Run `yarn install` 68 69 This will install both run-time project dependencies and developer tools listed 70 in [package.json](../package.json) file. 71 72 #### 3. Run `yarn start` 73 74 This command will build the app from the source files (`/src`) into the output 75 `/build` folder. As soon as the initial build completes, it will start the 76 Node.js server (`node build/server.js`) and [Browsersync](https://browsersync.io/) 77 with [HMR](https://webpack.github.io/docs/hot-module-replacement) on top of it. 78 79 > [http://localhost:3000/](http://localhost:3000/) — Node.js server (`build/server.js`)<br> 80 > [http://localhost:3000/graphql](http://localhost:3000/graphql) — GraphQL server and IDE<br> 81 > [http://localhost:3001/](http://localhost:3001/) — BrowserSync proxy with HMR, React Hot Transform<br> 82 > [http://localhost:3002/](http://localhost:3002/) — BrowserSync control panel (UI) 83 84 Now you can open your web app in a browser, on mobile devices and start 85 hacking. Whenever you modify any of the source files inside the `/src` folder, 86 the module bundler ([Webpack](http://webpack.github.io/)) will recompile the 87 app on the fly and refresh all the connected browsers. 88 89  90 91 Note that the `yarn start` command launches the app in `development` mode, 92 the compiled output files are not optimized and minimized in this case. 93 You can use `--release` command line argument to check how your app works 94 in release (production) mode: 95 96 ```shell 97 $ yarn start -- --release 98 ``` 99 *NOTE: double dashes are required* 100 101 102 ### How to Build, Test, Deploy 103 104 If you need just to build the app (without running a dev server), simply run: 105 106 ```shell 107 $ yarn run build 108 ``` 109 110 or, for a production build: 111 112 ```shell 113 $ yarn run build -- --release 114 ``` 115 116 or, for a production docker build: 117 118 ```shell 119 $ yarn run build -- --release --docker 120 ``` 121 122 *NOTE: double dashes are required* 123 124 After running this command, the `/build` folder will contain the compiled 125 version of the app. For example, you can launch Node.js server normally by 126 running `node build/server.js`. 127 128 To check the source code for syntax errors and potential issues run: 129 130 ```shell 131 $ yarn run lint 132 ``` 133 134 To launch unit tests: 135 136 ```shell 137 $ yarn run test # Run unit tests with Mocha 138 $ yarn run test:watch # Launch unit test runner and start watching for changes 139 ``` 140 141 By default, [Mocha](https://mochajs.org/) test runner is looking for test files 142 matching the `src/**/*.test.js` pattern. Take a look at `src/components/Layout/Layout.test.js` 143 as an example. 144 145 To deploy the app, run: 146 147 ```shell 148 $ yarn run deploy 149 ``` 150 151 The deployment script `tools/deploy.js` is configured to push the contents of 152 the `/build` folder to a remote server via Git. You can easily deploy your app 153 to [Azure Web Apps](https://azure.microsoft.com/en-us/services/app-service/web/), 154 or [Heroku](https://www.heroku.com/) this way. Both will execute `yarn install --production` 155 upon receiving new files from you. Note, you should only deploy the contents 156 of the `/build` folder to a remote server. 157 158 ### How to Update 159 160 If you need to keep your project up to date with the recent changes made to RSK, 161 you can always fetch and merge them from [this repo](https://github.com/kriasoft/react-starter-kit) 162 back into your own project by running: 163 164 ```shell 165 $ git checkout master 166 $ git fetch react-starter-kit 167 $ git merge react-starter-kit/master 168 $ yarn install 169 ```