UNPKG

6.8 kBMarkdownView Raw
1# Redux Toolkit
2
3![GitHub Workflow Status](https://img.shields.io/github/workflow/status/reduxjs/redux-toolkit/CI?style=flat-square)
4[![npm version](https://img.shields.io/npm/v/@reduxjs/toolkit.svg?style=flat-square)](https://www.npmjs.com/package/@reduxjs/toolkit)
5[![npm downloads](https://img.shields.io/npm/dm/@reduxjs/toolkit.svg?style=flat-square&label=RTK+downloads)](https://www.npmjs.com/package/@reduxjs/toolkit)
6
7**The official, opinionated, batteries-included toolset for efficient Redux development**
8
9(Formerly known as "Redux Starter Kit")
10
11## Installation
12
13### Using Create React App
14
15The recommended way to start new apps with React and Redux Toolkit is by using the [official Redux+JS template](https://github.com/reduxjs/cra-template-redux) for [Create React App](https://github.com/facebook/create-react-app), which takes advantage of React Redux's integration with React components.
16
17```sh
18npx create-react-app my-app --template redux
19```
20
21Or if you are a TypeScript user, use [cra-template-redux-typescript](https://github.com/reduxjs/cra-template-redux-typescript), which is based on that template
22
23```sh
24npx create-react-app my-app --template redux-typescript
25```
26
27### An Existing App
28
29Redux Toolkit is available as a package on NPM for use with a module bundler or in a Node application:
30
31```bash
32# NPM
33npm install @reduxjs/toolkit
34
35# Yarn
36yarn add @reduxjs/toolkit
37```
38
39It is also available as a precompiled UMD package that defines a `window.RTK` global variable.
40The UMD package can be used as a [`<script>` tag](https://unpkg.com/@reduxjs/toolkit/dist/redux-toolkit.umd.js) directly.
41
42## Purpose
43
44The **Redux Toolkit** package is intended to be the standard way to write Redux logic. It was originally created to help address three common concerns about Redux:
45
46- "Configuring a Redux store is too complicated"
47- "I have to add a lot of packages to get Redux to do anything useful"
48- "Redux requires too much boilerplate code"
49
50We can't solve every use case, but in the spirit of [`create-react-app`](https://github.com/facebook/create-react-app) and [`apollo-boost`](https://www.apollographql.com/blog/announcement/frontend/zero-config-graphql-state-management/), we can try to provide some tools that abstract over the setup process and handle the most common use cases, as well as include some useful utilities that will let the user simplify their application code.
51
52Because of that, this package is deliberately limited in scope. It does _not_ address concepts like "reusable encapsulated Redux modules", folder or file structures, managing entity relationships in the store, and so on.
53
54Redux Toolkit also includes a powerful data fetching and caching capability that we've dubbed "RTK Query". It's included in the package as a separate set of entry points. It's optional, but can eliminate the need to hand-write data fetching logic yourself.
55
56## What's Included
57
58Redux Toolkit includes these APIs:
59
60- `configureStore()`: wraps `createStore` to provide simplified configuration options and good defaults. It can automatically combine your slice reducers, adds whatever Redux middleware you supply, includes `redux-thunk` by default, and enables use of the Redux DevTools Extension.
61- `createReducer()`: that lets you supply a lookup table of action types to case reducer functions, rather than writing switch statements. In addition, it automatically uses the [`immer` library](https://github.com/mweststrate/immer) to let you write simpler immutable updates with normal mutative code, like `state.todos[3].completed = true`.
62- `createAction()`: generates an action creator function for the given action type string. The function itself has `toString()` defined, so that it can be used in place of the type constant.
63- `createSlice()`: accepts an object of reducer functions, a slice name, and an initial state value, and automatically generates a slice reducer with corresponding action creators and action types.
64- `createAsyncThunk`: accepts an action type string and a function that returns a promise, and generates a thunk that dispatches `pending/resolved/rejected` action types based on that promise
65- `createEntityAdapter`: generates a set of reusable reducers and selectors to manage normalized data in the store
66- The `createSelector` utility from the [Reselect](https://github.com/reduxjs/reselect) library, re-exported for ease of use.
67
68## RTK Query
69
70**RTK Query** is provided as an optional addon within the `@reduxjs/toolkit` package. It is purpose-built to solve the use case of data fetching and caching, supplying a compact, but powerful toolset to define an API interface layer for your app. It is intended to simplify common cases for loading data in a web application, eliminating the need to hand-write data fetching & caching logic yourself.
71
72RTK Query is built on top of the Redux Toolkit core for its implementation, using [Redux](https://redux.js.org/) internally for its architecture. Although knowledge of Redux and RTK are not required to use RTK Query, you should explore all of the additional global store management capabilities they provide, as well as installing the [Redux DevTools browser extension](https://github.com/reduxjs/redux-devtools), which works flawlessly with RTK Query to traverse and replay a timeline of your request & cache behavior.
73
74RTK Query is included within the installation of the core Redux Toolkit package. It is available via either of the two entry points below:
75
76```ts no-transpile
77import { createApi } from '@reduxjs/toolkit/query'
78
79/* React-specific entry point that automatically generates
80 hooks corresponding to the defined endpoints */
81import { createApi } from '@reduxjs/toolkit/query/react'
82```
83
84### What's included
85
86RTK Query includes these APIs:
87
88- `createApi()`: The core of RTK Query's functionality. It allows you to define a set of endpoints describe how to retrieve data from a series of endpoints, including configuration of how to fetch and transform that data. In most cases, you should use this once per app, with "one API slice per base URL" as a rule of thumb.
89- `fetchBaseQuery()`: A small wrapper around fetch that aims to simplify requests. Intended as the recommended baseQuery to be used in createApi for the majority of users.
90- `<ApiProvider />`: Can be used as a Provider if you do not already have a Redux store.
91- `setupListeners()`: A utility used to enable refetchOnMount and refetchOnReconnect behaviors.
92
93See the [**RTK Query Overview**](https://redux-toolkit.js.org/rtk-query/overview) page for more details on what RTK Query is, what problems it solves, and how to use it.
94
95## Documentation
96
97The Redux Toolkit docs are available at **https://redux-toolkit.js.org**.