Used by a an Enonic XP root project, builds an asset used by the browser at buildtime.
Supplies source code and a webpack setup to compile it.
API: webpack build
The webpack config takes two CLI arguments, mandatory from the root project. These are one the form of
where X is any of the capital-letter keys below.
REACT4XP_CONFIG_FILE: root-project-relative path to a react4xp-project constant-values JSON file.
- This file follows the format of, and is usually produced in the project by, react4xp-buildconstants.
- The used values from it can be overriden by CLI env arguments:
ROOT: absolute path to the root project
API: client runtime
In a standard react4xp setup, lib-react4xp serves the built client asset from
react4xp-client. The lib also offers
render controller-functions, that add a call to
react4xp-client URL, to the page contribution.
That client asset adds an object to the global namespace in the browser:
React4xp (or whatever the value
LIBRARY_NAME is). This object will contain the entries, under a key corresponding to their jsxPath.
In addition to those, there is
React4xp.CLIENT, which exposes three methods. These methods are also automatically
called in the browser when using the
render controller functions, but should you ever need them they are:
This corresponds to (and calls under the hood) ReactDOM's render function:
React4xp.CLIENT.render(Component, targetId, props, isPage, hasRegions);
Component(string or object, mandatory): jsxPath of a react4xp entry, or a reference to that object in the React4xp namespace:
targetId(string, mandatory): unique DOM id of the container where the entry will be rendered.
props(serializable object, optional): top-level data used by the entry
isPage(truthy/falsy, optional): truthy flags that the entry is the view of a page controller.
hasRegions(truthy/falsy, optional): truthy flags that the entry contains XP regions and that CLIENT may need to postprocess them.
render expects all necessary assets to already be loaded and run (this also happens automatically when using the
render): the entry asset, all its dependencies
and react/react-dom themselves.
This corresponds to (and calls under the hood) ReactDOM's hydrate function.
React4xp.CLIENT.hydrate(Component, targetId, props, isPage, hasRegions);
It's simply the hydrate version of
React4xp.CLIENT.render - the signature and arguments are the same.
Obviously, in addition to expecting assets to be loaded and run, it also expects an existing server-side-rendered DOM
inside the target container element. Again, this is handled by the controller function
This is purely a utility function for cases where the controller function
render has not already taken care of
things, but you need to render a react4xp entry from the client alone. Based on which entry or entries are requested, a
service from lib-react4xp is called to find all required assets for the entries and their dependencies, then those are
loaded, and finally
React4xp.CLIENT.render is called for each of them.
React4xp.CLIENT.renderWithDependencies(entriesWithTargetIdsAndProps, callback, serviceUrlRoot);
entriesWithTargetIdsAndProps(object, mandatory): keys in this object are are entry names (string: jsxPath) and the values are objects with a mandatory
targetIdattribute and an optional
propsattribute - which is a regular serializable object of any shape. Entries are loaded on the page in the order of the entry name keys.
callback(function, optional): called after the entire call chain is complete.
serviceUrlRoot(string, kinda-sorta-optional): root of the URL to the lib-react4xp's services - e.g. your app.
- For example, if they have the URLs
/_/service/my.app- without a trailing slash.
- You can skip this argument ONLY IF you define the constant SERVICE_URL_ROOT in global namespace before this call.
- For example, if they have the URLs