Skip to content

Latest commit

 

History

History
175 lines (132 loc) · 6.13 KB

getting-started.md

File metadata and controls

175 lines (132 loc) · 6.13 KB
Raw

Requirements

  • Mac OS X, Windows, or Linux
  • Yarn package + Node.js v6.12.3 or newer
  • Text editor or IDE pre-configured with React/JSX/ESlint (learn more)

Directory Layout

Before you start, take a moment to see how the project structure looks like:

.
├── /build/ # The folder for compiled output
├── /docs/ # Documentation files for the project
├── /node_modules/ # 3rd-party libraries and utilities
├── /public/ # Static files which are copied into the /build/public folder
├── /src/ # The source code of the application
│ ├── /actions/ # Redux Actions
│ ├── /components/ # Project components (in semantic folders see Terminology)
│ ├── /constants/ # Constant variables
│ ├── /reducers/ # Redux Reducers
│ ├── /routes/ # Page/screen components along with the routing information
│ ├── /store/ # Redux Store helpers
│ ├── /client.js # Client-side startup script
│ ├── /config.js # Global application settings
│ ├── /server.js # Server-side startup script
│ └── ... # Other core framework modules
├── /test/ # Unit and end-to-end tests
├── /tools/ # Build automation scripts and utilities
│ ├── /lib/ # Library for utility snippets
│ ├── /styleguide/ # Styleguideist tool dependencies
│ └── ... # Other tool library modules
│ ├── /build.js # Builds the project from source to output (build) folder
│ ├── /bundle.js # Bundles the web resources into package(s) through Webpack
│ ├── /clean.js # Cleans up the output (build) folder
│ ├── /copy.js # Copies static files to output (build) folder
│ ├── /deploy.js # Deploys your web application
│ ├── /postcss.config.js # Configuration for transforming styles with PostCSS plugins
│ ├── /render.js # Render static site
│ ├── /run.js # Helper function for running build automation tasks
│ ├── /runServer.js # Launches (or restarts) Node.js server
│ ├── /start.js # Launches the development web server with "live reload"
│ ├── /styleguide.config.js # Configurations for styleguideist
│ └── /webpack.config.js # Configurations for client-side and server-side bundles
├── Dockerfile # Commands for building a Docker image for production
├── package.json # The list of 3rd party libraries and utilities
└── yarn.lock # Fixed versions of all the dependencies

Quick Start

1. Get the latest version

You can start by cloning the latest version of React Starter Kit (RSK) on your local machine by running:

$ git clone https://REPO_DOMAIN/react-starter-kit MyAwesomeApp
$ cd MyAwesomeApp

2. Run yarn install

This will install both run-time project dependencies and developer tools listed in package.json file.

3. Run yarn start

This command will build the app from the source files (/src) into the output /build folder. As soon as the initial build completes, it will start the Node.js server (node build/server.js) and Browsersync with HMR on top of it.

http://localhost:3000/ — Node.js server (build/server.js) with Browsersync and HMR enabled > http://localhost:3001/ — Browsersync control panel (UI)

Now you can open your web app in a browser, on mobile devices and start hacking. Whenever you modify any of the source files inside the /src folder, the module bundler (Webpack) will recompile the app on the fly and refresh all the connected browsers.

browsersync

Note that the yarn start command launches the app in development mode, the compiled output files are not optimized and minimized in this case. You can use --release command line argument to check how your app works in release (production) mode:

$ yarn start --release

NOTE: double dashes are required

How to Build, Test, Deploy

If you need just to build the app (without running a dev server), simply run:

$ yarn build

or, for a production build:

$ yarn build --release

or, for a production docker build:

$ yarn build --release --docker

NOTE: double dashes are required

After running this command, the /build folder will contain the compiled version of the app. For example, you can launch Node.js server normally by running node build/server.js.

To check the source code for syntax errors and potential issues run:

$ yarn lint

To launch unit tests:

$ yarn test          # Run unit tests with Jest
$ yarn test-watch    # Launch unit test runner and start watching for changes

By default, Jest test runner is looking for test files matching the src/**/*.test.js pattern. Take a look at src/components/base/Layout/Layout.test.js as an example.

To deploy the app, run:

$ yarn deploy

The deployment script tools/deploy.js is configured to push the contents of the /build folder to a remote server via Git. You can easily deploy your app to Azure Web Apps, or Heroku this way. Both will execute yarn install --production upon receiving new files from you. Note, you should only deploy the contents of the /build folder to a remote server.

Styleguide

To work and launch the styleguide, run:

$ yarn styleguide

This will run a local server of the styleguide. It will show the components in the components folder.

For more information on how to document components etc. see React Styleguidist.

How to Update

If you need to keep your project up to date with the recent changes made to RSK, you can always fetch and merge them from this repo back into your own project by running:

$ git checkout master
$ git fetch react-starter-kit
$ git merge react-starter-kit/master
$ yarn install