mirror of https://github.com/status-im/reagent.git
109 lines
4.4 KiB
Markdown
109 lines
4.4 KiB
Markdown
# 0.8 Upgrade guide
|
|
|
|
The necessary changes depend on what environment you target, and
|
|
how you want to provide React.
|
|
|
|
| | Build | Browser | Node |
|
|
|---|---|---|---|
|
|
| Cljsjs | `:none` | Supported | Requires Cljs 1.10.238+ |
|
|
| Cljsjs | `:advanced` | Supported | Requires Cljs 1.10.238+ |
|
|
| `node modules` | `:none` | Known problems (1) | Supported |
|
|
| `node modules` | `:advanced` | Known problems (2) | Supported |
|
|
|
|
While Reagent 0.8 supports use with React from npm, there are known problems:
|
|
|
|
1. Closure can't properly handle React 16 CommonJS module pattern: https://github.com/google/closure-compiler/issues/2841
|
|
This causes the production React code being loaded even for development builds.
|
|
Using Chrome React Developer Tools with this setup will break Reagent.
|
|
|
|
2. Closure optimization currently breaks certain statically created objects which are
|
|
accessed dynamically in `ReactDOM/server`: https://github.com/facebook/react/issues/12368
|
|
Fixed by using `[com.google.javascript/closure-compiler-unshaded "v20180319"]` ([fix commit](https://github.com/google/closure-compiler/commit/c13cf48b98477e44409dba6359246bffa95b1c7b)), will be
|
|
the default in next ClojureScript release.
|
|
|
|
## Browser - Cljsjs
|
|
|
|
**This is the recommended setup.**
|
|
|
|
Using Reagent with Cljsjs packages doesn't require changes,
|
|
other than making sure you update Cljsjs React dependencies,
|
|
if you have direct dependencies to them.
|
|
|
|
To ensure Cljsjs libs are used instead of Node Modules, you can add `:npm-deps false`, which will make sure ClojureScript compiler doesn't look into `node_modules` directory if it exists.
|
|
|
|
## Browser - node modules
|
|
|
|
If `react`, `react-dom` and `create-react-class` are available in `node_modules`
|
|
directory, ClojureScript compiler will use these with Reagent.
|
|
|
|
If you don't want to call `npm` and manage `package.json`, you can use `:npm-deps` and `:install-deps` compiler options to
|
|
have ClojureScript install the packages automatically.
|
|
|
|
You can use `:process-shim` compiler option to provide `process.env.NODE_ENV`
|
|
constant which is used by JS code to enable development and production
|
|
builds. ClojureScript compiler will automatically set this constant to
|
|
`production` value when using `:advanced` optimizations. This enables
|
|
the React production build.
|
|
|
|
When using module processing, it should be possible to split output into several
|
|
[modules](https://clojurescript.org/reference/compiler-options#modules).
|
|
|
|
**Externs are required for use with node modules also!** React created objects
|
|
statically in several places and then accesses those dynamically. Closure-compiler
|
|
will in these cases rename the statically object properties, which will break
|
|
dynamically accessing the objects. Externs fix this by defining which properties
|
|
must not be renamed.
|
|
|
|
## Browser - loading React from CDNJS or custom Webpack bundle
|
|
|
|
**TODO: Not tested properly**
|
|
|
|
If you want to load React.js yourself from external JS file (CDN) or from custom bundle,
|
|
it should be possible to override the Cljsjs foreign-libs, while still using externs from Cljsjs packages. To override the foreign-libs, you can provide following compiler option:
|
|
|
|
```clj
|
|
:foreign-libs
|
|
[{:file "empty.js",
|
|
:provides ["react" "react-dom" "create-react-class" "react-dom/server"],
|
|
:requires [],
|
|
:global-exports {react React
|
|
react-dom ReactDOM
|
|
create-react-class createReactClass
|
|
react-dom/server ReactDOMServer}}]
|
|
```
|
|
|
|
You'll also need to create the mentioned `empty.js` file (FIXME: relative to `project.clj`?).
|
|
|
|
If your bundle provides other libraries, you could extern `:provides` and `:global-exports` (e.g. `prop-types`).
|
|
|
|
## NodeJS - Cljsjs
|
|
|
|
Requires https://github.com/clojure/clojurescript/commit/f7d611d87f6ea8a605eae7c0339f30b79a840b49
|
|
|
|
Available in 1.10.238
|
|
|
|
Reagent should use Cljsjs libraries by default even when running on Node.
|
|
|
|
## NodeJS - node modules
|
|
|
|
Install `react`, `react-dom` and `create-react-class` npm packages,
|
|
and ClojureScript should automatically use `require` to
|
|
load React for Reagent.
|
|
|
|
## Electron
|
|
|
|
???
|
|
|
|
## React-native
|
|
|
|
https://github.com/drapanjanas/re-natal/issues/128
|
|
|
|
## Common Problems
|
|
|
|
### Mismatch with Cljsjs and npm packages
|
|
|
|
If you have one npm package installed, e.g. `react`, you also need
|
|
to provide others (`react-dom` and `create-react-class`), else
|
|
Cljsjs packages would be used for these, and packages from different sources
|
|
don't work together.
|