lib-react4xp
React for XP: handling and rendering of pre-built React components in Enonic XP
This library runs on Enonic XP server side, and provides:
-
services that serve (autodetected and) pre-compiled React components and their dependency scripts to the browser, from a specific file structure. These services also provide headers for caching components and dependencies in the browser.
-
library of XP controller functions, that make it easy to blend React into XP components, in a variety of ways
-
server-side rendering option in XP, through the controller functions
-
client-side wrapper tailored for use with the services - itself available to the browser through one of the services.
Versions and compatibility
This library, lib-react4xp, is installed as a regular XP library in a parent app/project. It also needs to run alongside a suite of NPM packages. These are bundled (by dependency) in the react4xp package, so by installing that one, you get the necessary packages.
This package is needed both in this library and in the parent project that uses the library - and preferably with matching package version in both places. The library versions correspond with particular package versions. Whenever a library upgrade requires a new package version, whis table will be updated:
| lib-react4xp | @enonic/react4xp package (in both lib and app) |
|---|---|
3.4.2 |
3.1.2 |
3.4.1 |
3.1.1 |
3.4.0 |
3.1.0 |
3.3.0 |
3.1.0 |
3.2.0 |
3.0.18 |
3.1.0 |
3.0.17 |
3.0.0 |
3.0.6 |
Setup, option 1: The React4xp starter
If you’re starting with a fresh React4xp project and Enonic XP 7.x, by far the easiest way is to follow the instructions in the React4xp tutorial, and build it from there. The starter always uses the latest stable version of this library.
The React4xp starter is also available at enonic market or as open source at github.
Setup, option 2: Using React4xp in an existing project
If you want to skip the starter and inject React4xp in your own XP 7 project, you can. Follow these steps to get all the moving parts up and running:
0: Prerequisites
Assuming you have Enonic XP 7.x nicely installed, and you have an XP parent project app set up for it (a project where you want to use React4xp).
1: Add lib-react4xp
Two ways to add this library to a parent project: import it from an online repository, or build it from scratch:
1.1: Import it from a repository…
Insert into build.gradle in the parent project, under dependencies:
dependencies {
include 'com.enonic.lib:lib-react4xp:3.1.0'
}
repositories {
maven {
url 'http://repo.enonic.com/public'
}
}1.2: …OR fork and build it yourself
If you need / want to build the lib yourself instead of downloading it with Gradle, add these steps:
1.2.1. Clone or otherwise download the source code for this lib into its own root folder (not into XP_INSTALL or the parent project folder).
1.2.2. Make the version unique in the library’s gradle.properties, for example:
version = 3.1.01.2.3. Build it with gradle:
gradlew publishToMavenLocalGradle will build the library and install it into the local cache, available for other projects.
1.2.4. Finally, go to the parent project folder root. Make sure that the version you downloaded/built matches your local reference in build.gradle, under dependencies, e.g.:
dependencies {
include 'com.enonic.lib:lib-react4xp:3.4.0'
// Starting from 3.4.0 react4xp no longer provides org.json
// You may need to include it manually, if your code uses it
// include 'org.json:json:20220924'
}Other handy gradle dev tasks are clean and build.
2: Install NPM packages
Go to the parent XP project folder and use the command line to add these NPM packages as devDependencies:
npm install --save-dev @enonic/react4xpAgain, if you’re using a different version of this library than 3.1.0, the NPM package may need a different, matching version than @enonic/react4xp. See above.
Other development tools might be needed, depending on your setup:
npm add --save-dev @babel/cli@7 @babel/core@7 @babel/preset-env@7 @babel/preset-react@7 @babel/register@7 webpack@4 webpack-cli@3Etc.
3: Configuration: react4xp.properties
A few configuration properties are needed to guide the build steps.
When you’ve installed the NPM package @enonic/react4xp@3.0.6 or higher, you’ll find the general config file react4xp.properties at node_modules/react4xp/react4xp.properties. It has usage instructions and explanations in it for configuring your react4xp project by changing values and commenting in/out the different settings to your liking.
Copy it to your project folder at the root! Now it’s activated, and it will be used by node_modules/react4xp/react4xp.gradle (again, depends on react4xp@1.4.0 or higher) to build your project. If you use your own build.gradle setup instead, just look there for reference.
4: Gradle build setup
As of version 1.1.0 of the react4xp NPM package, the react4xp gradle build setup is shared in react4xp.gradle in the react4xp package.
As long as that’s installed and npm i (or similar) has been run before the gradle build, you can simply add this to your build.gradle:
apply from: "node_modules/react4xp/react4xp.gradle"If that for some reason is not an option for you, or you want a modified version of the setup, you can find react4xp.gradle here and build that into your project.
5: Gradle: XP component transpilation (optional)
If you want, or already have, Babel (etc) transpilation for your XP controllers and other assets, this needs to be done separately from the build tasks above! Make sure that the XP compilation step does not compile your react component source files!
Here’s an example from the starter; a gradle compile task that leaves .jsx files alone:
task compileXP(type: NodeTask) {
description 'Compile regular (non-React4xp) XP components from ES6, ignoring JSX components'
script = file('node_modules/@babel/cli/bin/babel.js')
args = ["src/main/resources", "--out-dir", "build/resources/main", "--ignore", "**/*.jsx"] // <-- Ignoring JSX in the XP structure
inputs.dir 'src/main/resources'
outputs.dir("build/resources/main")
}
jar.dependsOn += 'compileXP'(Why is this needed? For simple development after everything’s set up, React4xp detects and autocompiles .jsx files inside src/main/resources/site. This is to encourage a regular-XP-like structure, simply using .jsx files as part/page/layout views: just keep React entry components in the same folders, with the same names, as the corresponding XP components that use them (this structure is not enforced, though - using entryDirs and chunkDirs in react4xp.properties (see below), your react source files can basically be anywhere). However, the react files are handled differently from other XP components and assets, both at build- and runtime! For that reason they must be separated, in this example by using different file extensions: .jsx and .es6, respectively)
6: Build and run it all
From the parent project, this can now be run as a regular XP app:
enonic project deployOr, setting the environment variable XP_HOME (e.g. export XP_HOME=~/.enonic/sandboxes/myProjectSandbox/home), you can use regular gradle tasks such as clean, build, deploy.
Development
Getting started with working on this library locally.
Local build
Run this first to get set up.
gradlew buildNPM-linked mode
This lib (and consuming react4xp apps) requires the corresponding react4xp NPM packages. If you want to work with this lib with local versions of those packages too, it’s convenient to symlink them up under node_modules:
-
Download/fork/clone react4xp-npm from github to a separate source folder,
-
From that root react4xp-npm folder:
gradlew npmLink -
Back in the root folder of this lib, run react4xp-npm’s
getLinksscript (sorry, this script has no windows version yet, but should be fairly easy to reverse-engineer):sh relative/path/to/local/react4xp-npm/getlinks.sh -
Install the lib locally (see the next heading below),
-
From the root folder of your react4xp app project too, run
getLinkswith a relative path (same way as in step 3 above), -
Build the react4xp app.
Install the lib
To install the built library in local maven cache, available for building react4xp app(s) locally, follow the instructions above.