projecs by owner
(spring-react-boilerplate
An example application that uses a Spring Java backend with a React
frontend and can perform server-side rendering (SSR).
Another Boilerplate?
Yes, but with Java. It's inspired by the
spring-react-isomorphic
project, but at this point has been largely rebuilt from the ground up. The
frontend is build on
create-react-app
(CRA), though it was necessary to "eject" from CRA in order to apply some
changes for server.
The project also uses:
- Yarn for installing Node modules.
- Babel for transpiling the server-side render function.
- Hot module reloading (HMR) of React components
- Redux to manage state, both in the client and when rendering on the server.
- react-router for page routing, on client and server
- react-helmet for managing meta-data in the HTML
- Type checking with Flow.
Other Goodies
You also get:
- Project Lombok to cut down the Java
boilerplate - Jackson to serialize model data
before rendering on the server. For more information, see
this OpenJDK thread on the subject,
but summary is Nashorn won't (and actually can't) string-ify POJOs via
JSON.stringify, meaning it can't be used to serialise the Redux state.
Without this you'll have a bad time trying to use your Java objects in
your Redux state.
Changes from create-react-app
- Webpack output is a UMD bundle, which makes it possible to load it in
Nashorn - Hot reloading has been added
- LESS support has been added
- CRA's
polyfills.jshas been changed to be SSR-friendly - Possible to disable uglification during the production build by
setting theDEBUGenvironment variable (see below).
The render function
We implement a custom render function for Spring to call. The source code
is in src/main/js/react-render/renderer.js, and is compiled to ES5 syntax
during the Maven build. The build process also pulls in polyfills, to allow
React etc to work, and also the frontend's JSON manifest, in order to
locate the frontend's built assets. See the build.sh in the same
directory for how the final render code is assembled.
Running the code
Execute mvn if you have Maven already installed, or ./mvnw if you
don't. You'll need Java8
installed
either way at a MINIMUM version of 1.8.0_65. Older versions have a bug
that makes rendering brutally slow. Note that since React is not
thread-safe, Spring is configured to use a script engine per thread, and
each one will have to load the bundle when first initialises. You may want
to force refresh the website several times to make sure all the threads are
initialised, particular if you intend to measure performance.
To run the frontend in hot-module reloading mode, switch to another
terminal and execute:
cd src/main/app
yarn start
Your browser should automatically open
http://localhost:3000. Now when you edit your
files, the changes will be loaded in your browser automatically and, where
possible, be applied without losing the application's current state thanks
to react-hot-loader!
Conventions
Controllers that render views are suffixed with Controller. REST endpoints are
suffixed with Resource and handle requests under /api.
Testing the Webpack bundle / render function
In order to preempt runtime errors with Nashorn loading the bundle, a test
script is executed by Maven during the test-compile phase, located at
src/test/js/react-renderer/test.js. If this script fails, you can diagnose the problem
by running:
DEBUG=true mvn test-compile
This will rebuild the webpack bundle without minification, which should
make the cause of any error clearer.
It's easy to create a bundle that's broken on the server by including code that
expects a DOM - and that includes the Webpack style loader. This is the root of
most problems. You should note that server-side rendering does not require a
DOM - which is why src/main/js/react-renderer/polyfill.js doesn't provide
any window or document stubs.
Caveats
This isn't necessarily the best way to write a React application or a
Spring application. Pull requests welcome!