# Setup

## Installation

If you're using NPM, use

```bash
npm i --save react-ion-store
```

If you prefer yarn, use

```bash
yarn add react-ion-store
```

## The Store

The react-ion store is comprised of two kinds of values:

- mutable values and network calls
- immutable, static values

These translate in two properties you're using to configure the provider of your store:

- `store` **object**: the store's initial state: a collection of key/value pairs of all the keys you want to use and their accompanying, optional, default values.
- `staticKeys` **string[]**: a list of all the keys that are supposed to be static. Defining them here will lock their mutability within the react-ion API's.

### Setting up the StoreProvider

The StoreProvider is a parent component that wraps your entire app (or from whatever scope is needed), providing it with the store and staticKeys properties discussed in the topic above.

You only need to define your StoreProvider once in your app, preferably at the top-most level.

Many ProviderComponents are set within the `index.js` file, most notably theme providers for Material UI and JSS. Since we can consider our ValueMap as a theme for our store, we apply the logic the same way.

In this example, we're setting up the `store` and `staticKeys` in separate variables, before passing them to the store.

```jsx
// index.js
import React from "react";
import ReactDOM from "react-dom";
import StoreProvider from "react-ion-store";

import App from "./App";

const store = {
  title: "My static title!",
  subtitle: "A subtitle, also static!",
  counter: 0
};

const staticKeys = ["title", "subtitle"];

ReactDOM.render(
  <StoreProvider store={store} staticKeys={staticKeys}>
    <App />
  </StoreProvider>,
  document.getElementById("root")
);
```

### Static keys are optional

If you don't want to lock in keys as static, you don't need to pass a `staticKeys` prop. This is just as valid:

```jsx
const store = { counter: 0 };

ReactDOM.render(
  <StoreProvider store={store}>
    <App />
  </StoreProvider>,
  document.getElementById("root")
);
```

### Prevent reserved keywords

The terms `get`, `set` and `call` are reserved within the react-ion store, if you pass their keys in either of the ValueMap's parameters, they will be filtered out.

As an example, this will **not** work:

```js
const store = {
  get: () => "My static title!"
};

const staticKeys = ["get"];
```

## Using the store

We advise you to use the [withStore Higher-Order Component](hocs.html), but you can also use the `Consumer` component to access your store.

The Consumer works in the same way as the StoreProvider: you wrap it around your presentational logic:

```jsx
// MyTitle.js
import React from "react";
import { Consumer } from "react-ion-store";

export default class MyTitle extends React.Component {
  render() {
    return <Consumer>{store => <h1>{store.get("title")}</h1>}</Consumer>;
  }
}
```

### Drawbacks of Consumer

The way described above is not ideal. Ideally, we want to be able to:

- Get multiple values at once from the store
- Use the values in functions

`withStore` will pass the store to your props, allowing you to use it everywhere in your component! This is why you should definitely check out the [next section on getting values](getting_values.html), or you can go straight to the [Higher-Order Component API documentation](hocs.html).
