|
1 | | -# TSDX React User Guide |
| 1 | +<p align="center"> |
| 2 | + <img src="logo.svg" width="200px" height="200px" alt="logo"> |
| 3 | + <h2 align="center">useDebouncedLoader</h2> |
| 4 | + <p align="center"> |
| 5 | + ✨ Configurable hook to avoid flickering spinners |
| 6 | + <br> |
| 7 | + <br> |
| 8 | + <a href="https://frysztak.github.io/use-debounced-loader/">🎮 View Demo</a> |
| 9 | + </p> |
| 10 | +</p> |
2 | 11 |
|
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. |
| 12 | +## Table of Contents |
4 | 13 |
|
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`. |
| 14 | +- [📜 About](#-about) |
| 15 | +- [🏁 Getting started](#-getting-started) |
| 16 | +- [👨💻 Development](#-development) |
6 | 17 |
|
7 | | -> If you’re new to TypeScript and React, checkout [this handy cheatsheet](https://github.com/sw-yx/react-typescript-cheatsheet/) |
| 18 | +## 📜 About |
8 | 19 |
|
9 | | -## Commands |
| 20 | +**useDebouncedLoader** is a tiny React hook designed to debounce loaders/spinners. |
10 | 21 |
|
11 | | -TSDX scaffolds your new library inside `/src`, and also sets up a [Parcel-based](https://parceljs.org) playground for it inside `/example`. |
| 22 | +Using regular `debounce()` function (either from Lodash, many hookified versions or `debounceTime()` from RxJS) is a popular choice for |
| 23 | +debouncing spinners shown when your app is awaiting some API response. However, misadjusting its `delay` parameter can result in suboptimal UX. For instance: |
12 | 24 |
|
13 | | -The recommended workflow is to run TSDX in one terminal: |
| 25 | +- for relatively short debounce time (say, 100..300 ms) it can still cause a little bit of flickering. That's because `debounce()` propagates time on (time, when input stays high). |
| 26 | + To remedy this, you can increase debounce time, but then... |
| 27 | +- for relatively long debounce time (say, 600..800 ms) and relatively long response time, it can cause _lingering_. That's when spinner lingers on screen, even though |
| 28 | + request is already finished. This can turn out to be quite bad for User Experience, as your app will seem slower and less responsive. |
14 | 29 |
|
15 | | -```bash |
16 | | -npm start # or yarn start |
17 | | -``` |
18 | | - |
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`. |
34 | | - |
35 | | -## Configuration |
36 | | - |
37 | | -Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. |
| 30 | +This library aims to avoid both flickering and lingering spinners. It does so by introducing another parameter called `minimalTimeOn`. That's the minimal time spinner will stay on screen. |
38 | 31 |
|
39 | | -### Jest |
| 32 | +For more details, see (a very short!) API [docs](https://github.com/frysztak/use-debounced-loader/docs). You can also check out [comparison](https://frysztak.github.io/use-debounced-loader/) with a popular [useDebounce](https://github.com/xnimorz/use-debounce) library. |
40 | 33 |
|
41 | | -Jest tests are set up to run with `npm test` or `yarn test`. |
| 34 | +## 🏁 Getting Started |
42 | 35 |
|
43 | | -### Bundle analysis |
| 36 | +It's very simple. Just run |
44 | 37 |
|
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 |
| 38 | +```sh |
| 39 | +yarn add use-debounced-loader |
65 | 40 | ``` |
66 | 41 |
|
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 |
80 | | - |
81 | | -### GitHub Actions |
| 42 | +or |
82 | 43 |
|
83 | | -Two actions are added by default: |
84 | | - |
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 |
| 44 | +```sh |
| 45 | +npm install use-debounced-loader |
| 46 | +``` |
89 | 47 |
|
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: |
| 48 | +In your app, you might have code looking roughly like this: |
91 | 49 |
|
92 | | -```js |
93 | | -// ./types/index.d.ts |
94 | | -declare var __DEV__: boolean; |
| 50 | +```ts |
| 51 | +const { isLoading, data, ... } = useQuery(...); |
95 | 52 |
|
96 | | -// inside your code... |
97 | | -if (__DEV__) { |
98 | | - console.log('foo'); |
| 53 | +if (isLoading) { |
| 54 | + return <Spinner /> |
99 | 55 | } |
100 | 56 | ``` |
101 | 57 |
|
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`): |
113 | | - |
114 | | -```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 |
118 | | -``` |
| 58 | +All you need to do, is to debounce `isLoading`: |
119 | 59 |
|
120 | | -Alternatively, if you already have a git repo connected, you can set up continuous deployment with Netlify: |
| 60 | +```ts |
| 61 | +const { isLoading, data, ... } = useQuery(...); |
| 62 | +const debouncedIsLoading = useDebouncedLoader(isLoading); |
121 | 63 |
|
122 | | -```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 |
| 64 | +if (debouncedIsLoading) { |
| 65 | + return <Spinner /> |
| 66 | +} |
127 | 67 | ``` |
128 | 68 |
|
129 | | -## Named Exports |
130 | | - |
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. |
132 | | - |
133 | | -## Including Styles |
134 | | - |
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. |
| 69 | +and that's it! |
138 | 70 |
|
139 | | -## Publishing to NPM |
| 71 | +## 👨💻 Development |
140 | 72 |
|
141 | | -We recommend using [np](https://github.com/sindresorhus/np). |
| 73 | +Pull requests are very welcome. This projects has been bootstrapped with awesome [tsdx](https://tsdx.io), so getting started is very easy. All regular commands apply here as well. |
142 | 74 |
|
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 | | - }, |
158 | | -``` |
| 75 | +Demo app uses [Chakra-UI](https://chakra-ui.com/) and [react-timing-hooks](https://github.com/EricLambrecht/react-timing-hooks). |
159 | 76 |
|
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) |
| 77 | +<br /> |
| 78 | +<br /> |
| 79 | +<br /> |
| 80 | +Logo adapted from icon made by <a href="https://www.flaticon.com/authors/freepik" title="Freepik">Freepik</a> from <a href="https://www.flaticon.com/" title="Flaticon"> www.flaticon.com</a>. |
0 commit comments