README.md 7.8 KB
Newer Older
1
# ce-ui-common
2
3
4
5
**Common React hooks and components for CE UI applications**

## How to install this module in your app

6
### Prerequisites
7
8
9
First, make sure you have installed all of `ce-ui-common`'s peer dependencies into your app. You can find the list of peer dependencies in this repository's `package.json`.  

Latest lts (18.12.1) version of node should be sufficient. Anything above version 7 of npm should automatically install the peer dependencies of the `package.json`.
10
11
12

### Installation
You can install `ce-ui-common` in a dependent app directly from this git repository:
13
14
15
16
17
18
19
20
21
22
23
24

```
npm install git+https://gitlab.esss.lu.se/ccce/dev/ce-ui-common.git
```

You can use the `#<commit-ish>` syntax to install specific commits, branches, tags, even version ranges. For example, to install the `develop` branch, you can use: 

```
npm install git+https://gitlab.esss.lu.se/ccce/dev/ce-ui-common.git#develop
```

See the [npm-install docs](https://docs.npmjs.com/cli/v6/commands/npm-install) for more info about this syntax.
John Sparger's avatar
John Sparger committed
25

26
27
28
29
30
31
32
33
34
## Styling and design with Material UI

The styled and styling of the components are done with Material UI.  
If you have a need for changing anything css wise please refer the Material UI documentation:  
https://mui.com/system/styled/  
https://mui.com/material-ui/customization/theming/  
https://mui.com/material-ui/guides/interoperability/#styled-components  
https://mui.com/system/getting-started/the-sx-prop/  

35
## Available Scripts
John Sparger's avatar
John Sparger committed
36

37
In the project directory, you can run:
John Sparger's avatar
John Sparger committed
38

39
### `npm test`
John Sparger's avatar
John Sparger committed
40

41
42
Launches the test runner in the interactive watch mode.\
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
John Sparger's avatar
John Sparger committed
43

44
45
46
47
48
### `npm run cypress:run` & `npm run cypress:open`  

This will run cypress tests on the components that's been setup with at cypress testing library test.  
`npm run cypress:run` will run in headless state as for `npm run cypress:open` will open the cypress app gui and run in a browser.

49
50
51
52
53
54
55
56
57
58
### `npm run storybook`

Starts the interactive storybook server (see https://storybook.js.org/)

### `npm build storybook`

Builds the static storybook for this project (see https://storybook.js.org/)

### `npm run watch`

59
Starts a file watcher process which executes `npm run devInstall` whenever changes are made to files in the `src` directory. Now you can see live updates from edits to `ce-ui-common` in your client app's dev server (see discussion `devInstall`).
60
61
62

### `npm run devInstall`

63
Transpiles the module and rsyncs it tp `$CE_DEV_INSTALL_DIR/ce-ui-common`. This is useful when you are simultaneously working on this `ce-ui-common` and some dependent app. You can set `CE_DEV_INSTALL_DIR` in `.env.development` like this:
64
65
66
67
68
69

```
CE_DEV_INSTALL_DIR="somewhere/lib"
```

Once you have configured the install directory, you can start using your development version of ce-ui-common in the dependent app like this:
70
71

```
72
73
74
ce-ui-common$ npm run devInstall
ce-ui-common$ cd /path/to/dependent-app
dependent-app$ npm install --no-save somewhere/lib/ce-ui-common
75
76
```

77
78
79
80
81
This will create `ccce-ui-common` as a symolic link to the install dir in the dependent-app's `node_modules`, but it won't update the dependent-app's `package.json`. Whenever you make changes to ce-ui-common and need to push changes to the client app, just run `npm run devInstall` again. If the client app is using create-react-app, this will even trigger a hot reload of the dev server!

Note:  If you have some existing version of `ccce-ui-common` installed in the dependent-app (like from npm or git), `npm install --no-save somewhere/lib/ce-ui-common` will simply overwrite it with the local version. This is great for testing your local changes to `ce-ui-common` during development without screwing up the app's dependencies. When you want to revert back to the original version, just run: `npm install` again.

Warning! If `CE_DEV_INSTALL_DIR` or any of its ancestors contain a `node_modules` directory, webpack will try to resolve imports using those node modules! In other words, don't set `CE_DEV_INSTALL_DIR` to the child of any app or library project. Use some other external location instead.
82

83
84
85
86
87
88
89
90
91
92
93
### Fix when dev server in dependent-app won't pick up changes

Sometimes, especially when switching between an external and local version of the package, the webpack dev server in your client app will not show the new versions of the files even though you can see the new versions in `dependent-app/node_modules/ce-ui-common`. This is because the dev server has cached some files to make startup faster.

To fix this, simply stop the dev server, delete the cached files:
```
cd /path/to/dependent-app
rm node_modules/.cache/default-development/*
```
and restart the dev server.

94
95
96
97
98
99
100
101
102
103
### `npm run dist`

Transpiles the code using babel and stores the output in `dist`. Check `.babelrc` if you need to ignore certain files during transpilation or change some other configuration.

### `npm run pack`

Transpiles code using Babel and packages the module up into a .tgz

Warning! This is not the same as `npm pack`. It executes the extra step of transpiling the code with `npm run dist` before running `npm pack` to create the tarball. It is possible to automatically execute the transpilation by putting `npm run dist` step into the a `prepare` script. However, npm runs `prepare` when installing a module locally and this causes all sorts of problems in the scenario where a client app is installing the packaged version of this library.

104
### `npm run eject`
John Sparger's avatar
John Sparger committed
105

106
**Note: this is a one-way operation. Once you `eject`, you can't go back!**
John Sparger's avatar
John Sparger committed
107

108
If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
John Sparger's avatar
John Sparger committed
109

110
Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.
John Sparger's avatar
John Sparger committed
111

112
You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.
John Sparger's avatar
John Sparger committed
113

114
115
116
117
## Getting Started with Create React App

This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).

118
## Learn More
John Sparger's avatar
John Sparger committed
119

120
You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
John Sparger's avatar
John Sparger committed
121

122
To learn React, check out the [React documentation](https://reactjs.org/).
John Sparger's avatar
John Sparger committed
123

124
### Code Splitting
John Sparger's avatar
John Sparger committed
125

126
This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
John Sparger's avatar
John Sparger committed
127

128
### Analyzing the Bundle Size
John Sparger's avatar
John Sparger committed
129

130
This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
John Sparger's avatar
John Sparger committed
131

132
### Making a Progressive Web App
John Sparger's avatar
John Sparger committed
133

134
This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
John Sparger's avatar
John Sparger committed
135

136
### Advanced Configuration
John Sparger's avatar
John Sparger committed
137

138
This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
John Sparger's avatar
John Sparger committed
139

140
### Deployment
John Sparger's avatar
John Sparger committed
141

142
This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
John Sparger's avatar
John Sparger committed
143

144
### `npm run build` fails to minify
John Sparger's avatar
John Sparger committed
145

146
This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)