Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/geowarin/boot-react
A starter application with spring boot and react
https://github.com/geowarin/boot-react
hot-reload react redis redux spring-boot spring-session
Last synced: about 2 hours ago
JSON representation
A starter application with spring boot and react
- Host: GitHub
- URL: https://github.com/geowarin/boot-react
- Owner: geowarin
- License: mit
- Created: 2015-08-05T15:55:14.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-11-03T15:53:02.000Z (about 7 years ago)
- Last Synced: 2024-05-02T17:52:36.436Z (6 months ago)
- Topics: hot-reload, react, redis, redux, spring-boot, spring-session
- Language: JavaScript
- Homepage:
- Size: 349 KB
- Stars: 589
- Watchers: 43
- Forks: 155
- Open Issues: 6
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
# Spring boot and react hot starter
image:https://travis-ci.org/geowarin/boot-react.svg?branch=master["Build Status", link="https://travis-ci.org/geowarin/boot-react"]
image:https://ci.appveyor.com/api/projects/status/y3uw0gpo9dtec349?svg=true["Windows build Status", link="https://ci.appveyor.com/project/geowarin/boot-react"]
Be more productive with this simple project that uses the https://spring.io/blog/2015/06/17/devtools-in-spring-boot-1-3[spring dev tools]
and https://github.com/gaearon/babel-plugin-react-transform[react transform] for hot reloading.
Everything: backend, frontend and styles will be hot reloaded automatically.
See http://geowarin.github.io/spring-boot-and-react-hot.html[my article] for an in-depth explanation.
This project also sets up spring security and http://projects.spring.io/spring-session/[spring-sessions], which will
automatically store your sessions in Redis, allowing you to scale on multiple servers.
Both the frontend and the backend are fully tested.
## Developing
The Java code is available in the `backend` sub-project.
The `frontend` sub-project contains the javascript code.
In development you will have access to the awesome https://github.com/gaearon/redux-devtools[redux-dev-tools], which
will allow you keep track of your application state and undo/redo every action at will.
### Running the backend (recommended)
The recommended way to launch the server is to use your favorite java IDE.
The main method of the application is in the `BootReactApplication` class.
### Running the frontend (recommended)
**You will need node 6.0+ and yarn to run the dev server and build the project**
The frontend dev server will be automatically launched when you start the backend.
I strongly recommend that you install `yarn` on your development machine.
To install download the dependencies needed by the frontend do:
```
cd frontend
yarn
```
If you do not have the required binaries on your machine, you can use `./gradlew frontend:yarn_install` and `./gradlew frontend:start`.
Those two command will download the required node/yarn versions automatically and use them to run the node tasks.
### Alternatives for running the projects
There is also a gradle task to run the spring server: `./gradlew bootRun`.
### Hot reloading
With the dev server running, saving your javascript files or stylus assets will automatically trigger the hot reloading
(without browser refresh) of the application.
For the backend, recompiling the project in your IDE will trigger the reloading of the application's class loader.
### Sessions
Sessions are stored in Redis with spring-sessions.
Spring-sessions allows you to transparently persist the HttpSession on Redis.
This allows to distribute the load on multiple servers if you choose to.
The application relies on a stateless REST api.
When they authenticate, clients will be given a token.
They will save this token in their local storage and send it as an HTTP header (`x-auth-token`).
This allows the retrieval of the session data in Redis.
If you want to use a real redis, you can run the application with the `redis` profile.
If the `redis` profile is not active, your session will be stored in a map.
See: https://github.com/geowarin/boot-react/blob/master/backend/src/main/java/react/config/redis/EmbeddedSessionConfig.java[EmbeddedSessionConfig].
This is great in development but you should avoid it in production.
Summary:
|===
| Profile | description | uses `x-auth-token` header?
| `redis` | Use a real redis connecting on localhost by default. | Yes
| (`!redis`) | Uses a map to store sessions | Yes
|===
### Active profiles
If your run your project with gradle, the system properties won't be passed on to Spring.
See https://github.com/spring-projects/spring-boot/issues/832[this issue] for workarounds.
The simplest way to go is to specify active profiles in your IDE.
http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html[Check out the doc] to learn
more about profiles in Spring Boot.
To run the jar in production mode use the following command:
```
java -jar boot-react-0.0.1-SNAPSHOT.jar --spring.profiles.active=production 16:57:01
```
### Security
The application is configured to work with Spring Security.
It uses an in-memory authentication but you are free use
http://docs.spring.io/spring-security/site/docs/4.0.2.RELEASE/reference/htmlsingle/#jc-authentication[other implementations]
or to http://docs.spring.io/spring-security/site/docs/4.0.2.RELEASE/reference/htmlsingle/#core-services[roll your own].
### Redux
This project uses https://github.com/rackt/react-redux[Redux] to handle state and actions.
It is a simple library with very powerful dev tools.
Dan Abramov, the author of Redux, published a https://egghead.io/series/getting-started-with-redux[great Redux video tutorial].
I also suggest reading the https://github.com/rackt/react-redux/blob/master/docs/quick-start.md[redux quick start] to understand
how to architecture you application and the difference between containers and components.
Components are simple display elements that receive everything they need (state and actions) via props.
Containers are connected to Redux and as such, they can pull whatever properties they are interested in from the state
and bind actions to dispatch.
Those containers are only connecting simple components to Redux.
Small components are written using the https://facebook.github.io/react/blog/2015/10/07/react-v0.14.html#stateless-functional-components[stateless functional components syntax], i.e,
those component are pure render components and only their props will have an impact on the DOM.
Beware, hot reloading is not supported on functional components yet (see https://github.com/geowarin/boot-react/issues/13[this issue]) unless they are wrapped in a real Component.
We can http://rackt.github.io/redux/docs/recipes/WritingTests.html[write tests] on connected components,
but it is more effective to test them in isolation from Redux.
### Router push state
The project uses https://github.com/rackt/react-router[react-router] to handle routes.
You can choose several modes to handles the router history.
By default, the project uses the browser history,
which creates the nicest URLs (**/login**, **/private**, etc.).
In development, we use a dev server that
https://github.com/geowarin/boot-react/blob/master/frontend/server.js#L21-L24[proxies] requests to the index.
In production, we have to use a special https://github.com/geowarin/boot-react/blob/master/backend/src/main/java/react/config/SinglePageAppConfig.java[resource handler]
to redirect all non-asset requests to the index.
You can remove it if you choose to use memory history (no URL change) or hash history
(**/\#/login**, **/#/private**).
### Stylus
We use https://learnboost.github.io/stylus/[stylus] as a css preprocessor.
We also leverage two stylus modules:
* https://github.com/tj/nib[nib], which provides interesting mixins
* http://jeet.gs/[jeet], a powerful grid system
See examples of jeet http://codepen.io/collection/eilAH/[here].
In development, the styles are included by webpack, which enables hot reloading.
In production, we use the https://github.com/webpack/extract-text-webpack-plugin[Extract Text Plugin] to extract the css to a separate file.
## Static assets
If you want to include static assets like images in the project, please see https://github.com/geowarin/boot-react/issues/16[this issue],
which explains how to use the URL loader.
I'm real bad at creating logos but if you have time, I would be happy to include this by default in the project.
## Running the tests
The check tasks will run the tests in both the frontend and the backend:
```
./gradlew check
```
You can run the backend/frontend tests only with:
```
./gradlew backend/frontend:test
```
To test the backend, we use a simple https://github.com/geowarin/spring-spock-mvc[library] that wraps
spring mvc tests and makes them a bit nicer to read.
See the https://github.com/geowarin/boot-react/blob/master/backend/src/test/groovy/react/auth/AuthenticationSpec.groovy[auth-spec]
for an example.
To test the frontend, we use https://github.com/airbnb/enzyme[enzyme].
## Shipping
This command will generate an optimized bundle and include it in the jar.
```
./gradlew clean assemble
```
The jar will be available in `./backend/build/libs/boot-react-0.0.1-SNAPSHOT.jar`
You can then launch it with:
```
java -jar -Dspring.profiles.active=production backend/build/libs/boot-react-0.0.1-SNAPSHOT.jar
```
In production, you should use a real Redis instance so, please uncomment and edit the configuration file
(`backend/src/main/resources/application.yml`).
With spring boot 1.3, you can install the application http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/html/deployment-install.html#deployment-service[as a linux service]
NB: each application can be assembled with the `assemble` task so you can use `frontend:assemble` or `backend:assemble`.
The backend task depends on the frontend task.
## Docker
The project can create a docker container.
Just run:
```
./gradlew backend:buildDocker
```
And it will create a docker image named `boot-react/boot-react`.
```
> docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
boot-react/boot-react latest 5280d39f660f About a minute ago 138.9 MB
```
You can then run it with:
```
docker run -p 8080:8080 boot-react/boot-react
```
You can also pass arguments to the application like this:
```
docker run -p 8080:8080 boot-react/boot-react --spring.profiles.active=redis --spring.redis.host=redis
```
## Docker-compose
There is a simple `docker-compose.yml` in the root directory of the project.
Once you have built the application image with `./gradlew backend:buildDocker`, you can run:
```
docker-compose up -d
```
This will run the application together with a redis server.