# Introduction

Thanks for your interest in improving React Async! Contributions of any kind are welcome. Please refer to this guide before opening an issue or pull request.

This repo relies on Yarn workspaces, so you should [install](https://yarnpkg.com/en/docs/install) and use `yarn@1.3.2` or higher as the package manager for this project.

## Development guide

Please have the ***latest*** stable versions of the following on your machine

* node
* yarn

### Initial setup

To start working on React Async, clone the repo and bootstrap the project:

```bash
git clone https://github.com/async-library/react-async.git
cd react-async
yarn && yarn bootstrap && yarn test
```

Note that all work is done against the `next` branch, we only merge to `master` when doing a release.

### Working with Storybook

We use Storybook as a development environment, particularly for the DevTools. Spin it up using:

```bash
yarn start:storybook
```

This should open up Storybook in a browser at <http://localhost:6006/> Run it side-by-side with `yarn test --watch` during development. See [Testing](/contributing/introduction.md#testing).

### Linting

Use `yarn lint` to verify your code style before committing. It's highly recommended to install the Prettier and ESLint plugins for your IDE. Travis CI will fail your build on lint errors. Configure VS Code with the following settings:

```
"eslint.autoFixOnSave": true,
"eslint.packageManager": "yarn",
"eslint.options": {
  "cache": true,
  "cacheLocation": ".cache/eslint",
  "extensions": [".js", ".jsx", ".mjs", ".json", ".ts", ".tsx"]
},
"eslint.validate": [
  "javascript",
  "javascriptreact",
  {"language": "typescript", "autoFix": true },
  {"language": "typescriptreact", "autoFix": true }
],
"eslint.alwaysShowStatus": true
```

This should enable auto-fix for all source files, and give linting warnings and errors within your editor.

### Testing

Use the following command to test all packages in watch mode. Refer to the [Jest CLI options](https://jestjs.io/docs/en/cli#options) for details.

```bash
yarn test:watch
```

In general, this is sufficient during development. Travis CI will apply a more rigorous set of tests.

#### Testing for compatibility

```bash
yarn test:compat
```

This runs all tests using various versions of `react` and `react-dom`, to check for compatibility with older/newer versions of React. This is what CircleCI and Travis run.

### Working with the examples

In the `examples` folder, you will find sample React applications that use React Async in various ways with various other libraries. Please add a new example when introducing a major new feature. Make sure to add it to `now.json` so it is automatically deployed when merged to `master`.

To run sample examples on your local environments

```bash
yarn build:examples
yarn test:examples
yarn start:examples
```

### Resolving issues

Sometimes your dependencies might end up in a weird state, causing random issues, especially when working with the examples. In this case it often helps to run `yarn clean -y && yarn bootstrap`. This will delete `node_modules` from all packages/examples and do a clean install.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.react-async.com/contributing/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.