|
1 | | -# TSDX React User Guide |
| 1 | +# 🔀 React use bireducer [](https://github.com/soywod/react-use-bireducer/actions/workflows/test.yaml) [](https://app.codecov.io/gh/soywod/react-use-bireducer) [](https://www.npmjs.com/package/react-use-bireducer) |
2 | 2 |
|
3 | | -Congrats! You just saved yourself hours of work by bootstrapping this project with TSDX. Let’s get you oriented with what’s here and how to use it. |
| 3 | +React hook for managing effects within reducers. |
4 | 4 |
|
5 | | -> This TSDX setup is meant for developing React component libraries (not apps!) that can be published to NPM. If you’re looking to build a React-based app, you should use `create-react-app`, `razzle`, `nextjs`, `gatsby`, or `react-static`. |
6 | | -
|
7 | | -> If you’re new to TypeScript and React, checkout [this handy cheatsheet](https://github.com/sw-yx/react-typescript-cheatsheet/) |
8 | | -
|
9 | | -## Commands |
10 | | - |
11 | | -TSDX scaffolds your new library inside `/src`, and also sets up a [Parcel-based](https://parceljs.org) playground for it inside `/example`. |
12 | | - |
13 | | -The recommended workflow is to run TSDX in one terminal: |
| 5 | +## Installation |
14 | 6 |
|
15 | 7 | ```bash |
16 | | -npm start # or yarn start |
| 8 | +yarn add react-use-bireducer |
| 9 | +# or |
| 10 | +npm install react-use-bireducer |
17 | 11 | ``` |
18 | 12 |
|
19 | | -This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`. |
20 | | - |
21 | | -Then run the example inside another: |
22 | | - |
23 | | -```bash |
24 | | -cd example |
25 | | -npm i # or yarn to install dependencies |
26 | | -npm start # or yarn start |
27 | | -``` |
28 | | - |
29 | | -The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, we use [Parcel's aliasing](https://parceljs.org/module_resolution.html#aliases). |
30 | | - |
31 | | -To do a one-off build, use `npm run build` or `yarn build`. |
32 | | - |
33 | | -To run tests, use `npm test` or `yarn test`. |
| 13 | +## Usage |
34 | 14 |
|
35 | | -## Configuration |
| 15 | +The API is very close to `useReducer`, except that: |
36 | 16 |
|
37 | | -Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. |
| 17 | +- The state reducer returns `[State, Effect[]]` instead of `State` |
| 18 | +- You need to pass an effect reducer |
38 | 19 |
|
39 | | -### Jest |
| 20 | +```typescript |
| 21 | +import {useBireducer} from "react-use-bireducer"; |
40 | 22 |
|
41 | | -Jest tests are set up to run with `npm test` or `yarn test`. |
| 23 | +declare function stateReducer(state: State, action: Action): [State, Effect[]]; |
| 24 | +declare function effectReducer(effect: Effect): EffectCleanup | void; |
42 | 25 |
|
43 | | -### Bundle analysis |
44 | | - |
45 | | -Calculates the real cost of your library using [size-limit](https://github.com/ai/size-limit) with `npm run size` and visulize it with `npm run analyze`. |
46 | | - |
47 | | -#### Setup Files |
48 | | - |
49 | | -This is the folder structure we set up for you: |
50 | | - |
51 | | -```txt |
52 | | -/example |
53 | | - index.html |
54 | | - index.tsx # test your component here in a demo app |
55 | | - package.json |
56 | | - tsconfig.json |
57 | | -/src |
58 | | - index.tsx # EDIT THIS |
59 | | -/test |
60 | | - blah.test.tsx # EDIT THIS |
61 | | -.gitignore |
62 | | -package.json |
63 | | -README.md # EDIT THIS |
64 | | -tsconfig.json |
| 26 | +const [state, dispatch] = useBireducer(stateReducer, effectReducer, defaultState); |
65 | 27 | ``` |
66 | 28 |
|
67 | | -#### React Testing Library |
68 | | - |
69 | | -We do not set up `react-testing-library` for you yet, we welcome contributions and documentation on this. |
70 | | - |
71 | | -### Rollup |
72 | | - |
73 | | -TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details. |
74 | | - |
75 | | -### TypeScript |
76 | | - |
77 | | -`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs. |
78 | | - |
79 | | -## Continuous Integration |
| 29 | +See a complete [live example on |
| 30 | +CodeSandbox](https://codesandbox.io/s/react-use-bireducer-example-20n30w?file=/src/App.tsx). |
80 | 31 |
|
81 | | -### GitHub Actions |
| 32 | +## Development |
82 | 33 |
|
83 | | -Two actions are added by default: |
| 34 | +Development environment is managed by [Nix](https://nixos.org/). First |
| 35 | +you need to install it: |
84 | 36 |
|
85 | | -- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix |
86 | | -- `size` which comments cost comparison of your library on every pull request using [`size-limit`](https://github.com/ai/size-limit) |
87 | | - |
88 | | -## Optimizations |
89 | | - |
90 | | -Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations: |
91 | | - |
92 | | -```js |
93 | | -// ./types/index.d.ts |
94 | | -declare var __DEV__: boolean; |
95 | | - |
96 | | -// inside your code... |
97 | | -if (__DEV__) { |
98 | | - console.log('foo'); |
99 | | -} |
| 37 | +```bash |
| 38 | +curl -L https://nixos.org/nix/install | sh |
100 | 39 | ``` |
101 | 40 |
|
102 | | -You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions. |
103 | | - |
104 | | -## Module Formats |
105 | | - |
106 | | -CJS, ESModules, and UMD module formats are supported. |
107 | | - |
108 | | -The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found. |
109 | | - |
110 | | -## Deploying the Example Playground |
111 | | - |
112 | | -The Playground is just a simple [Parcel](https://parceljs.org) app, you can deploy it anywhere you would normally deploy that. Here are some guidelines for **manually** deploying with the Netlify CLI (`npm i -g netlify-cli`): |
| 41 | +Then you can start your development environment by spawning a Nix |
| 42 | +shell: |
113 | 43 |
|
114 | 44 | ```bash |
115 | | -cd example # if not already in the example folder |
116 | | -npm run build # builds to dist |
117 | | -netlify deploy # deploy the dist folder |
| 45 | +nix-shell |
118 | 46 | ``` |
119 | 47 |
|
120 | | -Alternatively, if you already have a git repo connected, you can set up continuous deployment with Netlify: |
| 48 | +Now you should be able to clone the repo and install Node.js |
| 49 | +dependencies: |
121 | 50 |
|
122 | 51 | ```bash |
123 | | -netlify init |
124 | | -# build command: yarn build && cd example && yarn && yarn build |
125 | | -# directory to deploy: example/dist |
126 | | -# pick yes for netlify.toml |
| 52 | +git clone https://github.com/soywod/react-use-bireducer.git |
| 53 | +cd react-use-bireducer |
| 54 | +yarn |
127 | 55 | ``` |
128 | 56 |
|
129 | | -## Named Exports |
| 57 | +You can leave the development environment either by killing your |
| 58 | +terminal or by entering the command `exit`. |
130 | 59 |
|
131 | | -Per Palmer Group guidelines, [always use named exports.](https://github.com/palmerhq/typescript#exports) Code split inside your React app instead of your React library. |
| 60 | +## Tests |
132 | 61 |
|
133 | | -## Including Styles |
| 62 | +Tests are handled by [Jest](https://jestjs.io/) (`.test` files) and |
| 63 | +[React Testing |
| 64 | +Library](https://testing-library.com/docs/react-testing-library/intro/) |
| 65 | +(`.spec` files). |
134 | 66 |
|
135 | | -There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like. |
136 | | - |
137 | | -For vanilla CSS, you can include it at the root directory and add it to the `files` section in your `package.json`, so that it can be imported separately by your users and run through their bundler's loader. |
138 | | - |
139 | | -## Publishing to NPM |
140 | | - |
141 | | -We recommend using [np](https://github.com/sindresorhus/np). |
142 | | - |
143 | | -## Usage with Lerna |
144 | | - |
145 | | -When creating a new package with TSDX within a project set up with Lerna, you might encounter a `Cannot resolve dependency` error when trying to run the `example` project. To fix that you will need to make changes to the `package.json` file _inside the `example` directory_. |
146 | | - |
147 | | -The problem is that due to the nature of how dependencies are installed in Lerna projects, the aliases in the example project's `package.json` might not point to the right place, as those dependencies might have been installed in the root of your Lerna project. |
148 | | - |
149 | | -Change the `alias` to point to where those packages are actually installed. This depends on the directory structure of your Lerna project, so the actual path might be different from the diff below. |
150 | | - |
151 | | -```diff |
152 | | - "alias": { |
153 | | -- "react": "../node_modules/react", |
154 | | -- "react-dom": "../node_modules/react-dom" |
155 | | -+ "react": "../../../node_modules/react", |
156 | | -+ "react-dom": "../../../node_modules/react-dom" |
157 | | - }, |
| 67 | +```bash |
| 68 | +yarn test |
158 | 69 | ``` |
159 | 70 |
|
160 | | -An alternative to fixing this problem would be to remove aliases altogether and define the dependencies referenced as aliases as dev dependencies instead. [However, that might cause other problems.](https://github.com/palmerhq/tsdx/issues/64) |
| 71 | +## Sponsoring |
| 72 | + |
| 73 | +[](https://github.com/sponsors/soywod) |
| 74 | +[](https://www.paypal.com/paypalme/soywod) |
| 75 | +[](https://ko-fi.com/soywod) |
| 76 | +[](https://www.buymeacoffee.com/soywod) |
| 77 | +[](https://liberapay.com/soywod) |
0 commit comments