Skip to content

Commit adc5bef

Browse files
wallace-sfwallace-sf
authored
Merge pull request #6 from flow-build/docs/DAT-388
Docs/DAT-388
2 parents 32424a8 + 6dc91a8 commit adc5bef

File tree

1 file changed

+138
-108
lines changed

1 file changed

+138
-108
lines changed

‎README.md‎

Lines changed: 138 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,181 +1,211 @@
1-
# TSDX React w/ Storybook User Guide
21

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.
2+
# React MQTT Workflow Manager
43

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`.
4+
React MQTT Workflow Manager is a React component library designed to wrap all [MQTT](https://mqtt.org/) sub logic behind the scenes. It deals only with events, no commands. The manager comunicates with your broker to dispatch actions in your front-end application. The library is focused to work with [Workflow API Layer](https://github.com/flow-build/workflow-api).
65

7-
> If you’re new to TypeScript and React, checkout [this handy cheatsheet](https://github.com/sw-yx/react-typescript-cheatsheet/)
6+
## Table of contents
87

9-
## Commands
8+
- [Installation](#installation)
9+
- [Dependencies](#dependencies)
10+
- [Usage](#usage)
11+
- [Example of usage](#example-of-usage)
12+
- [Properties](#properties)
13+
- [WorkflowManagerConfig](#workflowmanagerconfig)
14+
- [Hooks](#hooks)
15+
- [Running locally](#running-locally)
16+
- [Authors](#authors)
17+
- [License](#license)
1018

11-
TSDX scaffolds your new library inside `/src`, and also sets up a [Parcel-based](https://parceljs.org) playground for it inside `/example`.
19+
## [Installation](installation)
1220

13-
The recommended workflow is to run TSDX in one terminal:
21+
```bash
22+
npm install @flowbuild/react-mqtt-workflow-manager --save
23+
```
24+
or
1425

1526
```bash
16-
npm start # or yarn start
27+
yarn add @flowbuild/react-mqtt-workflow-manager
1728
```
29+
## [Dependencies](dependencies)
1830

19-
This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`.
31+
The `WorkflowManager` component [peer depends](https://docs.npmjs.com/files/package.json#peerdependencies) on the [React](https://www.npmjs.com/package/react) and [React DOM](https://www.npmjs.com/package/react-dom) in version 18.
32+
33+
```bash
34+
npm i react@18 react-dom@18
35+
```
36+
## [Usage](usage)
2037

21-
Then run either Storybook or the example playground:
2238

23-
### Storybook
39+
1. Before the componente usage, set the store with `WorkflowManagerConfig.setStore`.
2440

25-
Run inside another terminal:
41+
```tsx
42+
// App.tsx
2643

27-
```bash
28-
yarn storybook
29-
```
44+
import * as React from 'react';
3045

31-
This loads the stories from `./stories`.
46+
import { WorkflowManagerConfig } from '@flowbuild/react-mqtt-workflow-manager';
3247

33-
> NOTE: Stories should reference the components as if using the library, similar to the example playground. This means importing from the root project directory. This has been aliased in the tsconfig and the storybook webpack config as a helper.
48+
import { store } from './store'; // Your redux store
3449

35-
### Example
3650

37-
Then run the example inside another:
51+
WorkflowManagerConfig.setStore(store);
3852

39-
```bash
40-
cd example
41-
npm i # or yarn to install dependencies
42-
npm start # or yarn start
53+
// ...
4354
```
4455

45-
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).
56+
2. Wrap your application with `WorkflowManager`.
4657

47-
To do a one-off build, use `npm run build` or `yarn build`.
58+
```tsx
59+
// App.tsx
4860

49-
To run tests, use `npm test` or `yarn test`.
61+
import * as React from 'react';
5062

51-
## Configuration
63+
import { Provider } from 'react-redux';
64+
import { WorkflowManager, WorkflowManagerConfig } from '@flowbuild/react-mqtt-workflow-manager';
5265

53-
Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly.
66+
import { store } from './store'; // Your redux store
5467

55-
### Jest
5668

57-
Jest tests are set up to run with `npm test` or `yarn test`.
69+
WorkflowManagerConfig.setStore(store);
5870

59-
### Bundle analysis
71+
export const App: React.FC = () => {
72+
return (
73+
<Provider store={store}>
74+
<WorkflowManager
75+
brokerUrl="ws://broker.mqttdashboard.com:8000/mqtt"
76+
options={{
77+
clientId: `clientId-${Math.random().toString(36).substring(2, 9)}`,
78+
keepalive: 60,
79+
}}
80+
>
81+
{/* Your child component here */}
82+
</WorkflowManager>
83+
</Provider>
84+
);
85+
};
86+
```
87+
88+
3. Lastly, set `workflowManagerReducer` to your store reducers.
6089

61-
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`.
90+
```ts
91+
import { configureStore, createSlice } from '@reduxjs/toolkit';
6292

63-
#### Setup Files
93+
import { workflowManagerReducer, WorkflowManagerConfig } from '@flowbuild/react-mqtt-workflow-manager';
6494

65-
This is the folder structure we set up for you:
95+
const myAppSlice = createSlice({
96+
name: '@myApp',
97+
...
98+
});
99+
100+
export const store = configureStore({
101+
reducer: { myApp: myAppSlice.reducer, workflowManagerReducer },
102+
});
66103

67-
```txt
68-
/example
69-
index.html
70-
index.tsx # test your component here in a demo app
71-
package.json
72-
tsconfig.json
73-
/src
74-
index.tsx # EDIT THIS
75-
/test
76-
blah.test.tsx # EDIT THIS
77-
/stories
78-
Thing.stories.tsx # EDIT THIS
79-
/.storybook
80-
main.js
81-
preview.js
82-
.gitignore
83-
package.json
84-
README.md # EDIT THIS
85-
tsconfig.json
86104
```
87105

88-
#### React Testing Library
106+
## [Example of usage](example-of-usage)
89107

90-
We do not set up `react-testing-library` for you yet, we welcome contributions and documentation on this.
108+
See a complete example of usage [here](https://github.com/flow-build/react-mqtt-workflow-manager/tree/master/app/).
91109

92-
### Rollup
110+
## [Properties](properties)
93111

94-
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.
112+
Property | Type | Required | Description
113+
--- | --- | --- | ---
114+
`brokerUrl` | *string* | false | URL to connect to broker. Use full URL like ws://
115+
`options` | *IClientOptions* | false | MQTT client options. See [MQTT.js](https://github.com/mqttjs/MQTT.js/blob/main/types/lib/client-options.d.ts).
95116

96-
### TypeScript
117+
## [WorkflowManagerConfig](workflowmanagerconfig)
97118

98-
`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs.
119+
The library also exposes methods and utilities for your commodity. They can be used out of the context of react components.
99120

100-
## Continuous Integration
121+
### setStore(store)
101122

102-
### GitHub Actions
123+
The library use your redux store to dispatch actions. This is used to dispatch internal actions control and for your applications.
103124

104-
Two actions are added by default:
125+
### getMqttClient()
105126

106-
- `main` which installs deps w/ cache, lints, tests, and builds on all pushes against a Node and OS matrix
107-
- `size` which comments cost comparison of your library on every pull request using [size-limit](https://github.com/ai/size-limit)
127+
A utility method to be used out of context to react components. Be careful; the method must be able to return `null` if an error happens when setting connect. [See here](https://github.com/mqttjs/MQTT.js/blob/main/README.md#client).
108128

109-
## Optimizations
129+
### subscribe(topic/topic array/topic object, [options])
110130

111-
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:
131+
Works like exactly like [mqtt#subscribe](https://github.com/mqttjs/MQTT.js/blob/main/README.md#mqttclientsubscribetopictopic-arraytopic-object-options-callback), but the library implements validations and internal rules.
112132

113-
```js
114-
// ./types/index.d.ts
115-
declare var __DEV__: boolean;
133+
### subscribe(topic/topic array/topic object, [options])
116134

117-
// inside your code...
118-
if (__DEV__) {
119-
console.log('foo');
120-
}
121-
```
135+
Works like exactly like [mqtt#unsubscribe](https://github.com/mqttjs/MQTT.js/blob/main/README.md#mqttclientunsubscribetopictopic-array-options-callback), but the library implements validations and internal rules.
136+
137+
## [Hooks](hooks)
138+
139+
Some hooks are exported for commodity.
140+
141+
### useMqtt()
142+
143+
The hook returns a object contaning `client`, `status` and `error`.
122144

123-
You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions.
145+
Property | Type | Default value | Description
146+
--- | --- | --- | ---
147+
`client` | *MqttClient* | `null` | See type [here](https://github.com/mqttjs/MQTT.js/blob/main/types/lib/client.d.ts)
148+
`status` | *string* | `offline` | `connecting`, `connected`, `disconnected`, `reconnecting`, `offline` or `error`.
149+
`error` | *Error* | `null` |
124150

125-
## Module Formats
151+
### useSubscribe()
126152

127-
CJS, ESModules, and UMD module formats are supported.
153+
Returns `WorkflowManagerConfig.subscribe` for your commodity.
128154

129-
The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found.
155+
### UseUnsubscribe()
130156

131-
## Deploying the Example Playground
157+
Returns `WorkflowManagerConfig.unsubscribe` for your commodity.
132158

133-
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`):
159+
## [Running locally](running-locally)
160+
161+
Clone the project
134162

135163
```bash
136-
cd example # if not already in the example folder
137-
npm run build # builds to dist
138-
netlify deploy # deploy the dist folder
164+
git clone https://github.com/flow-build/react-mqtt-workflow-manager.git
139165
```
140166

141-
Alternatively, if you already have a git repo connected, you can set up continuous deployment with Netlify:
167+
Go to the project directory
142168

143169
```bash
144-
netlify init
145-
# build command: yarn build && cd example && yarn && yarn build
146-
# directory to deploy: example/dist
147-
# pick yes for netlify.toml
170+
cd react-mqtt-workflow-manager
148171
```
149172

150-
## Named Exports
173+
Install dependencies
151174

152-
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.
175+
```bash
176+
npm install
177+
```
153178

154-
## Including Styles
179+
Start the development server
155180

156-
There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like.
181+
```bash
182+
npm run dev
183+
```
157184

158-
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.
185+
Go to the project example directory
159186

160-
## Publishing to NPM
187+
```bash
188+
cd app
189+
```
161190

162-
We recommend using [np](https://github.com/sindresorhus/np).
191+
Install de example dependencies
163192

164-
## Usage with Lerna
193+
```bash
194+
npm install
195+
```
165196

166-
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_.
197+
Start the example application
167198

168-
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.
199+
```bash
200+
npm run start
201+
```
169202

170-
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.
171203

172-
```diff
173-
"alias": {
174-
- "react": "../node_modules/react",
175-
- "react-dom": "../node_modules/react-dom"
176-
+ "react": "../../../node_modules/react",
177-
+ "react-dom": "../../../node_modules/react-dom"
178-
},
179-
```
204+
## [Authors](authors)
205+
206+
[@wallace-sf](https://www.github.com/wallace-sf)
207+
208+
209+
## [License](license)
180210

181-
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)
211+
[MIT](https://choosealicense.com/licenses/mit/)

0 commit comments

Comments
 (0)