playframework / play-java-angular-seed

:maple_leaf: Java Play 2.7.x + Angular 8 with Angular CLI seed project with full-fledged build process

Java Play Angular Seed

Use play framework to develop the web application backend/services and frontend using Angular CLI, all in a totally integrated workflow and single unified console. This approach will deliver perfect development experience without CORS hassle.

Read more @ http://bit.ly/2AStvhK

Used Versions

• Play Framework: 2.8.0
• Angular: 8.x.x
• Angular CLI: 8.0.3

How to use it?

Prerequisites

• Node.js (version 10 or higher)
• JDK (recommend version 1.8 or higher)

Let's get started,

• Fork or clone this repository.

• Used any of the following SBT commands which will intern trigger frontend associated npm scripts.

    sbt clean           # Clean existing build artifacts

    sbt stage           # Build your application from your project’s source directory

    sbt run             # Run both backend and frontend builds in watch mode

    sbt dist            # Build both backend and frontend sources into a single distribution artifact

    sbt test            # Run both backend and frontend unit tests

• This seed is not using scala play views. All the views and frontend associated routes are served via Angular code base under ui directory.

Complete Directory Layout

├── /app/                                 # The backend source (controllers, models, services)
│     └── /controllers/                   # Backend controllers
│           └── FrontendController.scala  # Asset controller wrapper serving frontend assets and artifacts
├── /conf/                                # Configurations files and other non-compiled resources (on classpath)
│     ├── application.conf                # Play application configuratiion file.
│     ├── logback.xml                     # Logging configuration
│     └── routes                          # Routes definition file
├── /logs/                                # Log directory
│     └── application.log                 # Application log file
├── /project/                             # Contains project build configuration and plugins
│     ├── FrontendCommands.scala          # Frontend build command mapping configuration
│     ├── FrontendRunHook.scala           # Forntend build PlayRunHook (trigger frontend serve on sbt run)
│     ├── build.properties                # Marker for sbt project
│     └── plugins.sbt                     # SBT plugins declaration
├── /public/                              # Frontend build artifacts will be copied to this directory
├── /target/                              # Play project build artifact directory
│     ├── /universal/                     # Application packaging
│     └── /web/                           # Compiled web assets
├── /test/                                # Contains unit tests of backend sources
├── /ui/                                  # React frontend source (based on Create React App)
│     ├── /e2e/                           # End to end tests folder
│     ├── /node_modules/                  # 3rd-party frontend libraries and utilities
│     ├── /src/                           # The frontend source code (modules, componensts, models, directives, services etc.) of the application
│     │     ├── karma.conf.js             # Karma configuration file
│     │     └── proxy.conf.json           # UI proxy configuration      
│     ├── .angular.json                   # Angular CLI configuration
│     ├── .editorconfig                   # Define and maintain consistent coding styles between different editors and IDEs
│     ├── .gitignore                      # Contains ui files to be ignored when pushing to git
│     ├── package.json                    # NPM package configuration.
│     ├── README.md                       # Contains all user guide details for the ui
│     ├── tsconfig.json                   # Contains typescript compiler options
│     └── tslint.json                     # Lint rules for the ui
├── .gitignore                            # Contains files to be ignored when pushing to git
├── build.sbt                             # Play application SBT configuration
├── LICENSE                               # License Agreement file
├── README.md                             # Application user guide
└── ui-build.sbt                          # SBT command hooks associated with frontend npm scripts 

What is new in here?

FrontendCommands.scala

• Frontend build command mapping configuration.

    ├── /project/
    │     ├── FrontendCommands.scala

FrontendRunHook.scala

• PlayRunHook implementation to trigger npm run start on sbt run.

    ├── /project/
    │     ├── FrontendRunHook.scala

FrontendController.scala

• Asset controller wrapper serving frontend assets and artifacts.

    ├── /app/                                 
    │     └── /controllers/                   
    │           └── FrontendController.scala

ui-build.sbt

• This file contains the build task hooks to trigger frontend npm scripts on sbt command execution.

npm scripts

• New and modified npm scripts of Angular CLI generated package.json.
• Check UI README.md to see all available frontend build tasks.

├── /ui/                       
│     ├── package.json          

proxy.conf.json

• Used to proxy play backend API when running the project on watch mode.

├── /ui/                       
│     ├── proxy.conf.json          

Routes

├── /conf/      
│     ├── routes

• The following route configuration map index.html to entry route (root). This should be placed as the initial route.

GET        /             controllers.FrontendController.index()

• All API routes should be prefixed with API prefix defined under application.conf (Default prefix apiPrefix = "api")

Example API route:

GET        /api/summary  controllers.HomeController.appSummary

• The following route is being used to serve frontend associated build artifacts (css, js) and static assets (images, etc.). This should be placed as the final route.

GET        /*file        controllers.FrontendController.assetOrDefault(file)

Note: On production build all the front end Angular build artifacts will be copied to the public/ui folder.

Can be used to implement any front end/ui build!

• Simply replace the ui directory with the build of your choice
• Make output directory ROOT/public/
• Implement a proxy to localhost:9000

Looking for some other frontend framework or language choice

• Scala Play Angular Seed
• Scala Play React Seed
• Java Play React Seed
• Scala Play Vuejs Seed by Duncan Nevin
• Java Play Vuejs Seed by Duncan Nevin

Contributors

Yohan Gomez	Lahiru Jayamanna	Gayan Attygalla	Anuradha Gunasekara

License

This software is licensed under the MIT license

play-java-angular-seed's Issues

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Unable to access public assets when productionized with Docker

I have a Play framework project (2.6.19). I have integrated Angular7, in the way shown in this repo. It runs fine locally. I have Dockerized the application for production deployment, as suggested in #5.

But when I deploy the Dockerized app and go to the ${site_name}/ url, no content is loaded on the page and I see the following errors in the browser console.

Loading failed for the <script> with source “${site_name}/runtime.b57bf819d5bdce77f1c7.js”.
Loading failed for the <script> with source “${site_name}/polyfills.f5ce8ecea387adbb1689.js”.
Loading failed for the <script> with source “${site_name}/main.7b584dffbb7d3f5a51bd.js”.

My directory structure looks just like this seed. I don't pull in these files explicitly myself in my index.html. However, after the Angular build, the index.html file in the public directory includes the following lines:

<script type="text/javascript" src="runtime.b57bf819d5bdce77f1c7.js"></script>
<script type="text/javascript" src="polyfills.f5ce8ecea387adbb1689.js"></script>
<script type="text/javascript" src="main.7b584dffbb7d3f5a51bd.js"></script>

This seems to be the the expected behavior and should not be a problem as far as I can see, since the public directory also contains these files: runtime.b57bf819d5bdce77f1c7.js, polyfills.f5ce8ecea387adbb1689.js, main.7b584dffbb7d3f5a51bd.js.

But then why is the app not able to find these scripts, if they're located in the public directory, at the same level as the index.html file?

Warnings when runing sbt and sbt test

sbt
[warn] Found version conflict(s) in library dependencies; some are suspected to be binary incompatible: [warn] * org.webjars:webjars-locator-core:0.33 is selected over 0.32 [warn] +- com.typesafe:npm_2.12:1.2.1 (depends on 0.32) [warn] +- com.typesafe.sbt:sbt-web:1.4.3 (scalaVersion=2.12, sbtVersion=1.0) (depends on 0.32) [warn] * org.codehaus.plexus:plexus-utils:3.0.17 is selected over {2.1, 1.5.5} [warn] +- org.apache.maven:maven-settings:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-repository-metadata:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-aether-provider:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-model:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-core:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-artifact:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-settings-builder:3.2.2 (depends on 3.0.17) [warn] +- org.apache.maven:maven-model-builder:3.2.2 (depends on 3.0.17) [warn] +- org.sonatype.plexus:plexus-sec-dispatcher:1.3 (depends on 1.5.5) [warn] +- org.eclipse.sisu:org.eclipse.sisu.plexus:0.0.0.M5 (depends on 2.1) [warn] * com.google.guava:guava:23.0 is selected over {10.0.1, 16.0, 20.0} [warn] +- io.methvin:directory-watcher:0.3.2 (depends on 23.0) [warn] +- com.fasterxml.jackson.datatype:jackson-datatype-guava:2.8.8 (depends on 10.0.1) [warn] +- org.eclipse.sisu:org.eclipse.sisu.plexus:0.0.0.M5 (depends on 10.0.1) [warn] +- com.spotify:docker-client:8.9.0 (depends on 10.0.1) [warn] Run 'evicted' to see detailed eviction warnings

sbt run

[warn] * com.google.guava:guava:22.0 is selected over {19.0, 20.0} [warn] +- com.typesafe.play:play_2.12:2.6.9 (depends on 22.0) [warn] +- org.reflections:reflections:0.9.11 (depends on 20.0) [warn] +- com.google.inject:guice:4.1.0 (depends on 19.0) [warn] * com.typesafe.akka:akka-stream_2.12:2.5.8 is selected over 2.4.20 [warn] +- com.typesafe.play:play-streams_2.12:2.6.9 (depends on 2.5.8) [warn] +- com.typesafe.akka:akka-http-core_2.12:10.0.11 () (depends on 2.4.20) [warn] * com.typesafe.akka:akka-actor_2.12:2.5.8 is selected over 2.4.20 [warn] +- com.typesafe.akka:akka-slf4j_2.12:2.5.8 () (depends on 2.5.8) [warn] +- com.typesafe.akka:akka-stream_2.12:2.5.8 () (depends on 2.5.8) [warn] +- com.typesafe.play:play_2.12:2.6.9 (depends on 2.5.8) [warn] +- com.typesafe.akka:akka-parsing_2.12:10.0.11 () (depends on 2.4.20) [warn] Run 'evicted' to see detailed eviction warnings

Why you kept one controller in scala ? Is this required ?

https://github.com/yohangz/java-play-angular-seed/tree/master/app/controllers

one controller is in scala FrontendController.scala

How to work with Docker?

I have a Play framework project (2.6.19). I have integrated Angular7, in the way shown in this repo. So if I run sbt "project frontend" run or sbt "project frontend" dist, then the corresponding hooks for setting up Angular are invoked, and the app is able to run correctly.

But my Play project is Dockerized (via https://www.scala-sbt.org/sbt-native-packager/formats/docker.html). When I run sbt "project frontend" docker:publish, the usual binary for the Play app is created and Docker uses that for the entrypoint. However, none of the hooks for building the Angular project are invoked. When I access the app after pushing the Docker image, it runs as before (Angular is not running).

Is there a way I can insert a hook so that the Angular code is built, upon sbt "project frontend" docker:publish or sbt "project frontend" docker:publishLocal? I was thinking perhaps sbt "project frontend" docker:publish would be calling sbt "project frontend" dist under the hood, but apparently it is not.