Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Format Markdown (.md) files by Prettier #1461

Merged
merged 1 commit into from
Nov 15, 2017
Merged

Format Markdown (.md) files by Prettier #1461

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 26 additions & 23 deletions docs/data-fetching.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,29 @@
## Data Fetching

At a bare minimum you may want to use [HTML5 Fetch API][fetch] as an HTTP client utility for
making Ajax request to the [data API server][nodeapi]. This API is supported natively in all the
major browsers except for IE (note, that Edge browser does support Fetch).

**React Starter Kit** is pre-configured with [`whatwg-fetch`][wfetch] polyfill for the browser
environment and [`node-fetch`][nfetch] module for the server-side environment (see
[`src/createFetch.js`](../src/createFetch.js)), allowing you to use the `fetch(url, options)`
method universally in both the client-side and server-side code bases.

In order to avoid the amount of boilerplate code needed when using the raw `fetch(..)`
function, a simple wrapper was created that provides a base URL of the data API server, credentials
(cookies), CORS etc. For example, in a browser environment the base URL of the data API server
might be an empty string, so when you make an Ajax request to the `/graphql` endpoint it's being
sent to the same origin, and when the same code is executed on the server, during server-side
rendering, it fetches data from the `http://api:8080/graphql` endpoint (`node-fetch` doesn't
support relative URLs for obvious reasons).

Because of these subtle differences of how the `fetch` method works internally, it makes total
sense to pass it as a `context` variable to your React application, so it can be used from either
routing level or from inside your React components as follows:
At a bare minimum you may want to use [HTML5 Fetch API][fetch] as an HTTP client
utility for making Ajax request to the [data API server][nodeapi]. This API is
supported natively in all the major browsers except for IE (note, that Edge
browser does support Fetch).

**React Starter Kit** is pre-configured with [`whatwg-fetch`][wfetch] polyfill
for the browser environment and [`node-fetch`][nfetch] module for the
server-side environment (see [`src/createFetch.js`](../src/createFetch.js)),
allowing you to use the `fetch(url, options)` method universally in both the
client-side and server-side code bases.

In order to avoid the amount of boilerplate code needed when using the raw
`fetch(..)` function, a simple wrapper was created that provides a base URL of
the data API server, credentials (cookies), CORS etc. For example, in a browser
environment the base URL of the data API server might be an empty string, so
when you make an Ajax request to the `/graphql` endpoint it's being sent to the
same origin, and when the same code is executed on the server, during
server-side rendering, it fetches data from the `http://api:8080/graphql`
endpoint (`node-fetch` doesn't support relative URLs for obvious reasons).

Because of these subtle differences of how the `fetch` method works internally,
it makes total sense to pass it as a `context` variable to your React
application, so it can be used from either routing level or from inside your
React components as follows:

#### Route Example

Expand Down Expand Up @@ -50,11 +54,10 @@ class Post extends React.Component {

#### Related articles

* [That's so fetch!](https://jakearchibald.com/2015/thats-so-fetch/) by [Jake Archibald](https://twitter.com/jaffathecake)

* [That's so fetch!](https://jakearchibald.com/2015/thats-so-fetch/) by
[Jake Archibald](https://twitter.com/jaffathecake)

[fetch]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
[wfetch]: https://github.com/github/fetchno
[nfetch]: https://github.com/bitinn/node-fetch
[nodeapi]: https://github.com/kriasoft/nodejs-api-starter

74 changes: 41 additions & 33 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@

### Requirements

* Mac OS X, Windows, or Linux
* [Yarn](https://yarnpkg.com/) package + [Node.js](https://nodejs.org/) v6.5 or newer
* Text editor or IDE pre-configured with React/JSX/Flow/ESlint ([learn more](./how-to-configure-text-editors.md))
* Mac OS X, Windows, or Linux
* [Yarn](https://yarnpkg.com/) package + [Node.js](https://nodejs.org/) v6.5 or
newer
* Text editor or IDE pre-configured with React/JSX/Flow/ESlint
([learn more](./how-to-configure-text-editors.md))

### Directory Layout

Expand Down Expand Up @@ -42,9 +44,9 @@ Before you start, take a moment to see how the project structure looks like:
└── yarn.lock # Fixed versions of all the dependencies
```

**Note**: The current version of RSK does not contain a Flux implementation.
It can be easily integrated with any Flux library of your choice. The most
commonly used Flux libraries are [Flux](http://facebook.github.io/flux/),
**Note**: The current version of RSK does not contain a Flux implementation. It
can be easily integrated with any Flux library of your choice. The most commonly
used Flux libraries are [Flux](http://facebook.github.io/flux/),
[Redux](http://redux.js.org/) and [Relay](http://facebook.github.io/relay/).

### Quick Start
Expand All @@ -62,7 +64,8 @@ $ cd MyApp

Alternatively, you can start a new project based on RSK right from
[WebStorm IDE](https://www.jetbrains.com/help/webstorm/generating-a-project-from-a-framework-template.html#d88767e51),
or by using [Yeoman generator](https://www.npmjs.com/package/generator-react-fullstack).
or by using
[Yeoman generator](https://www.npmjs.com/package/generator-react-fullstack).

#### 2. Run `yarn install`

Expand All @@ -73,31 +76,34 @@ in [package.json](../package.json) file.

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](https://browsersync.io/)
with [HMR](https://webpack.github.io/docs/hot-module-replacement) on top of it.

> [http://localhost:3000/](http://localhost:3000/) — Node.js server (`build/server.js`)
with Browsersync and HMR enabled<br>
> [http://localhost:3000/graphql](http://localhost:3000/graphql) — GraphQL server and IDE<br>
> [http://localhost:3001/](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](http://webpack.github.io/)) will recompile the
app on the fly and refresh all the connected browsers.
Node.js server (`node build/server.js`) and
[Browsersync](https://browsersync.io/) with
[HMR](https://webpack.github.io/docs/hot-module-replacement) on top of it.

> [http://localhost:3000/](http://localhost:3000/) — Node.js server
> (`build/server.js`) with Browsersync and HMR enabled\
> [http://localhost:3000/graphql](http://localhost:3000/graphql) — GraphQL server
> and IDE\
> [http://localhost:3001/](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](http://webpack.github.io/)) will recompile the app on the fly
and refresh all the connected browsers.

![browsersync](https://dl.dropboxusercontent.com/u/16006521/react-starter-kit/brwosersync.jpg)

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:
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:

```shell
$ yarn start -- --release
```
*NOTE: double dashes are required*

_NOTE: double dashes are required_

### How to Build, Test, Deploy

Expand All @@ -119,7 +125,7 @@ or, for a production docker build:
$ yarn run build -- --release --docker
```

*NOTE: double dashes are required*
_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
Expand All @@ -139,8 +145,8 @@ $ yarn run test:watch # Launch unit test runner and start watching for change
```

By default, [Mocha](https://mochajs.org/) test runner is looking for test files
matching the `src/**/*.test.js` pattern. Take a look at `src/components/Layout/Layout.test.js`
as an example.
matching the `src/**/*.test.js` pattern. Take a look at
`src/components/Layout/Layout.test.js` as an example.

To deploy the app, run:

Expand All @@ -150,16 +156,18 @@ $ yarn run 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](https://azure.microsoft.com/en-us/services/app-service/web/),
or [Heroku](https://www.heroku.com/) 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.
to
[Azure Web Apps](https://azure.microsoft.com/en-us/services/app-service/web/),
or [Heroku](https://www.heroku.com/) 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.

### 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](https://github.com/kriasoft/react-starter-kit)
back into your own project by running:
you can always fetch and merge them from
[this repo](https://github.com/kriasoft/react-starter-kit) back into your own
project by running:

```shell
$ git checkout master
Expand Down
24 changes: 16 additions & 8 deletions docs/how-to-configure-text-editors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ Create a new project based on **React Starter Kit template**

![react-project-template-in-webstorm](https://dl.dropboxusercontent.com/u/16006521/react-starter-kit/webstorm-new-project.png)

Make sure that **JSX** support is enabled in your project. This is set by default, if you create a new project based on React.js template.
Make sure that **JSX** support is enabled in your project. This is set by
default, if you create a new project based on React.js template.

![jsx-support-in-webstorm](https://dl.dropboxusercontent.com/u/16006521/react-starter-kit/webstorm-jsx.png)

Expand All @@ -21,9 +22,12 @@ Enable **ESLint** support

![eslint-support-in-webstorm](https://dl.dropboxusercontent.com/u/16006521/react-starter-kit/webstorm-eslint.png)

Enable **CSSComb** by following the instructions [here](https://github.com/csscomb/jetbrains-csscomb).
Enable **CSSComb** by following the instructions
[here](https://github.com/csscomb/jetbrains-csscomb).

**If you have trouble with autoreloading** try to disable "safe write" in `File > Settings > System Settings > Use "safe write" (save changes to a temporary file first)`
**If you have trouble with autoreloading** try to disable "safe write" in
`File > Settings > System Settings > Use "safe write" (save changes to a
temporary file first)`

### Atom

Expand All @@ -49,25 +53,29 @@ Install local npm packages
yarn add --dev eslint babel-eslint eslint-plugin-react stylelint
```

*You may need to restart atom for changes to take effect*
_You may need to restart atom for changes to take effect_

### SublimeText

Install SublimeText packages
Easiest with [Package Control](https://packagecontrol.io/) and then "Package Control: Install Package" (Ctrl+Shift+P)
Install SublimeText packages\
Easiest with [Package Control](https://packagecontrol.io/) and then "Package Control:
Install Package" (Ctrl+Shift+P)

* [Babel](https://packagecontrol.io/packages/Babel)
* [Sublime-linter](http://www.sublimelinter.com/en/latest/)
* [SublimeLinter-contrib-eslint](https://packagecontrol.io/packages/SublimeLinter-contrib-eslint)
* [SublimeLinter-contrib-stylelint](https://packagecontrol.io/packages/SublimeLinter-contrib-stylelint)

You can also use [SublimeLinter-contrib-eslint_d](https://packagecontrol.io/packages/SublimeLinter-contrib-eslint_d) for faster linting.
You can also use
[SublimeLinter-contrib-eslint_d](https://packagecontrol.io/packages/SublimeLinter-contrib-eslint_d)
for faster linting.

Set Babel as default syntax for a particular extension:

* Open a file with that extension,
* Select `View` from the menu,
* Then `Syntax` `->` `Open all with current extension as...` `->` `Babel` `->` `JavaScript (Babel)`.
* Then `Syntax` `->` `Open all with current extension as...` `->` `Babel` `->`
`JavaScript (Babel)`.
* Repeat this for each extension (e.g.: .js and .jsx).

Install local npm packages
Expand Down
Loading