The main goal of this project is to make available to unemployed developers source code for a state-of-the-art web application the likes of which only exist as intellectual property visible exclusively to employed experts who have signed non-disclosure agreements and can't let you see it or learn how they made everything work together.

You should not have to get hired before learning how to do a thing the right way

The other goal is to assemble enough functionality into one free example application that people think twice before starting another one-feature, no edge-case, example and exacerbating the already overwhelming starting point option overload. Hopefully this will persuade a few people to direct that energy instead into improving what already exists. To this end I have made, over the course of the past 4 years, the world's biggest, most detailed database of web technology selling points so things could be compared easily in broad daylight without the hype and selective disclosure of a typical product/project sales page. See below for a sample slice of it.

"There are already lots of little example apps!!" (written in all different styles) "Software development is always taught using lots of inconsistent simple examples!!" "Approaches are a matter of personal preference and shouldn't be imposed" (on beginners who don't have strong opinions yet)

"Bloated!!"

There's a strange resistance to using big examples to educate instead of small ones, but no complaints about using cars to teach automechanics instead of go-karts. There are lots of reasons to do this. Here are some I thought of:

1. Real code answers every question, not just what the authors of tutorials choose to answer through
their choices of simplifications.

2. To make something new as an expert would do it, it's much easier to copy and modify a thing
made by experts, no matter how complex, than to synthesize the missing details removed for the 
sake of simplicity, out of nothing, no matter how simple. To do the latter requires full 
comprehension of a menagerie of inconsistent resources with inconsistent contexts. To do the 
former takes a few searches, a few replacements and a little bug fixing.

3. If you want a job making commercial-grade code, you should study commercial-grade code,
not tutorial-grade code. Anything you learn in a tutorial must be handled with caution 
because corners have probably been cut (e.g. the entire back-end), and it probably doesn't 
show you the exact way anyone does it on a real job. The difference between exact and almost 
exact is the difference between ten stones balanced on top of each other and those stones lying on
the ground. You keep your job and the company makes money only if *everything* works.

4. Tutorials show you how you *can* use a feature of the technology but often they 
do so in situations when in real life you would not do things that way. This can cost a lot of 
time. It's just as important to know when to use a technology's features as it is to know how.

5. If you want to know how fast an app using a particular technology will build, run and test 
before investing the time to learn it - and you should - then you need source code for a big 
app before you even write Hello World.

6. If you want to know the complexity limits a technology will place on your app before you
commit to using it, there's no better way than to see a complex example made with that technology.

7. It's a whole lot easier to vet an idea or accept an approach others have taken when you have
a complete application with all of its edge cases to show you what needs to be accommodated. 
By containing many edge cases, a big application will quickly answer the common learner's question:
"Why isn't this done the easy way I think it should be done?", or "What if we tried X instead?"
Without access to lots of edge cases in the beginning, you can go down the wrong road for a long time.

I've had a peculiarly difficult time making the case to software development educators to provide a single, giant example app for their students akin to what they work on every day for their clients and employers. So here's this attempt at one from unemployed me. No NDA needed to see it.

This application has been constructed by combining small open source demos into one big application. It's basically a structure that would have been had all the tutorial experts worked together instead of separately. Coming from different demos, the features of the app are not related to each other and it won't make any sense to have them together but the point is just to demonstrate how things should work technically, so that's okay. I took these projects and integrated/restructured/restyled their code according to the following prioritization. Disagreements in approach between two influences are resolved by the lower authority yielding to the higher one:

1. Angular Style Guide by Google (see change log for updates)
2. Tour of Heroes (ngModules, Routing, App Specs, HTTP, Server Communication versions) by Google
3. Angular CLI by Google and the community
4. Redux Docs Redux.org
5. JHipster Example - Bank accounts by @jdubois
6. JHipster Example - Blog by @mraible
7. scalable-architecture-demo - P2P Typing Game by @mgechev
8. ngrx example app - book collection by @MikeRyan52
9. angular-seed-advanced by @mgechev + @NathanWalker + community
10. FAMN example by @implustech
11. ng2-state-talk - drag/editable notes by @JavascriptMick
12. feathers-starter-react-redux-login-roles - Feathers back end with auth by @eddyystop
13. rangle-starter Angular 2 with TypeScript and Redux version - counter by @SethDavenport

In addition to the features from these demos, I added one of my own. I replaced

14. this other project which was made with JQuery and Google Scripts. The data is contained in this Google Sheet and served as JSON by a Google script.

A huge thanks to those who created the example demos from which I put together this amalgam.

While the goal of the project is to combine the wisdom of different experts, nobody can resist introducing improvements when there's no obvious case against doing so. So you will see a couple of practices in this project that came from my head rather than the sources of expertise from which the project was assembled. If you can think of reasons not to do these things, please let me know.

1. I put the Redux store reducers in app/core/store separate from the feature directories located under app and did not make folders for reducers, actions, and effects. There is a many-to-many relationship between Redux store slices and features. So putting the Redux code for a given slice into the same directory as one of the features that uses it doesn't make sense. How do you decide which feature gets it?

2. As much as practical the names of files in a directory begin with the directory name. I did this to prevent directories from having a mixture of unrelated concerns. If a directory in a source demo had files for two different things, I created more directories. I thought about removing that part of the file name, src/app/app.page.ts -> src/app/page.ts, for the sake of DRY, but that makes it too confusing when you are working on multiple files with the same names and different directories.

3. I noticed a lot of duplication and boilerplate of identical CRUD code for each of my types of entities. So I made utility functions and the related actions and models for each of three types of store slice - entities, id lists, and slices (everything else).

4. I came up with a mini lexicon of file types to keep file names shorter and more expressive. A "page" is understood to be a smart @Component class that fills the page and might have a router-outlet and route configurations. A "guard" is understood to be an @Injectable "service" class that returns a boolean. A "routing" is a @NgModule class that contains route configurations. So I memorize this simple lexicon, and drop the redundant, less-clear words from the names. For example, I use the name app.page.ts rather than app.component.ts or app-page.component.ts. I use auth.guard.ts instead of auth-guard.service.ts. I use books.routing.ts instead of books-routing.module.ts.

That's it. It shouldn't be too hard to remember these, and in return you will have consistent, short, expressive file names.

Before you can build this project, you must install and configure the following dependencies on your machine:

1. Node.js: We use Node to run a development web server and build the project. Depending on your system, you can install Node either from source or as a pre-packaged bundle. Be sure to use an LTS version of node nvm is handy for managing different versions of node.
2. Yarn: We use Yarn to manage Node dependencies. Depending on your system, you can install Yarn either from source or as a pre-packaged bundle.

After installing Node, you should be able to run the following command to install development tools. You will only need to run this command when dependencies change in package.json.

yarn install

We use yarn scripts and Webpack as our build system.

Run the following commands in two separate terminals to create a blissful development experience where your browser auto-refreshes when files change on your hard drive.

./mvnw
yarn start

Yarn is also used to manage CSS and JavaScript dependencies used in this application. You can upgrade dependencies by specifying a newer version in package.json. You can also run yarn update and yarn install to manage dependencies. Add the help flag on any command to see how you can use it. For example, yarn help update.

The yarn run command will list all of the scripts available to run for this project.

For example, to add Leaflet library as a runtime dependency of your application, you would run following command:

yarn add --exact leaflet

To benefit from TypeScript type definitions from DefinitelyTyped repository in development, you would run following command:

yarn add --dev --exact @types/leaflet

Then you would import the JS and CSS files specified in library's installation instructions so that Webpack knows about them:

Edit src/main/webapp/app/vendor.ts file:

import 'leaflet/dist/leaflet.js';

Edit src/main/webapp/content/css/vendor.css file:

@import '~leaflet/dist/leaflet.css';

Note: there are still few other things remaining to do for Leaflet that we won't detail here.

For further instructions on how to develop with JHipster, have a look at Using JHipster in development.

You can also use Angular CLI to generate some custom client code.

For example, the following command:

ng generate component my-component

will generate few files:

create src/main/webapp/app/my-component/my-component.component.html
create src/main/webapp/app/my-component/my-component.component.ts
update src/main/webapp/app/app.module.ts

To optimize the GreatBigExampleApplication application for production, run:

./mvnw -Pprod clean package

This will concatenate and minify the client CSS and JavaScript files. It will also modify index.html so it references these new files. To ensure everything worked, run:

java -jar target/*.war

Then navigate to http://localhost:8090 in your browser.

Refer to Using JHipster in production for more details.

To launch your application's tests, run:

./mvnw clean test

Unit tests are run by Karma and written with Jasmine. They're located in src/test/javascript/ and can be run with:

yarn test

UI end-to-end tests are powered by Protractor, which is built on top of WebDriverJS. They're located in src/test/javascript/e2e and can be run by starting Spring Boot in one terminal (./mvnw spring-boot:run) and running the tests (yarn run e2e) in a second one.

Performance tests are run by Gatling and written in Scala. They're located in src/test/gatling and can be run with:

./mvnw gatling:execute

For more information, refer to the Running tests page.

You can use Docker to improve your JHipster development experience. A number of docker-compose configuration are available in the src/main/docker folder to launch required third party services. For example, to start a postgresql database in a docker container, run:

docker-compose -f src/main/docker/postgresql.yml up -d

To stop it and remove the container, run:

docker-compose -f src/main/docker/postgresql.yml down

You can also fully dockerize your application and all the services that it depends on. To achieve this, first build a docker image of your app by running:

./mvnw package -Pprod docker:build

Then run:

docker-compose -f src/main/docker/app.yml up -d

For more information refer to Using Docker and Docker-Compose, this page also contains information on the docker-compose sub-generator (yo jhipster:docker-compose), which is able to generate docker configurations for one or several JHipster applications.

To configure CI for your project, run the ci-cd sub-generator (yo jhipster:ci-cd), this will let you generate configuration files for a number of Continuous Integration systems. Consult the Setting up Continuous Integration page for more information.

If you get stuck on anything, no matter how little, please let me know. I know how the little things are what cause the problems and I don't want you to have any problems.

I agree. That's why I created utility functions to hold all the common code and got rid of plural names to enable generic handling, and I replaced static action type definitions with dynamic functions that combine slice nouns and action verbs. It also turns out that most of the tricky RxJS code is also boilerplate code that now resides inside functions that you don't have to mess with most of the time. So you should be able to get productive on an app that uses Observables without first having to be an expert at them, which is hard.

That's a pretty big benefit. What could be seen as costs of doing that?

1. You lose some static type checking of action types.

Given that most Redux apps are done with React and React doesn't have any static type checking at all, I decided that was a small price to pay. You can also mix this approach and the other one if you really want to. Use the general, un-type-checked, CRUD stuff for ordinary parts of your app (most of it), and use hard-coded, specialty action types when you really need TypeScript's compiler to help you.

Here's some code from the ngrx example app that gives you type checking for the action types. You won't get these checks using my approach.

export function reducer(state: Entities<Book> = initialEntities<Book>({}, slices.BOOK, actions, {}),
  action: book.Actions | collection.Actions): Entities<Book> {
  switch (action.type) {
    ...

action: book.Actions | collection.Actions means that action must be an object of a class in this union of two unions of class definitions

That gives us two checks: action.type must be a string value among the union of string values of the type properties of the classes that action can be. If any of the case values are not among this union of string values, Typescript will point that out to you. And same with action.payload. It must be an object with the structure of the payload property of one of the classes that action can be.

2. Using only generic action classes like LoadSuccess instead of SearchComplete, the dispatch calls in your components will be more explicit and refer to details of the store.

I see this as a plus in most cases. Otherwise you have extraneous levels of abstraction and you have to look into three files to see exactly what's going on. In most cases, the same person is writing the component, action and reducer files, so what's the point in hiding details in one of them from the other? Now you can get the whole story by reading one line of code. You should decouple things when the need arises, but you can overdo it too.

I got the idea from the ngrx example app. I asked about it once and was told that it was done for performance reasons but I'm not sure under what conditions they apply.

This makes it possible to have the application work offline. It also lets your objects have some persisted attributes and some transient, UI attributes without it affecting the api code. The way this works is that the UI lets you display things before they have been persisted to the server. Then a request to persist happens. The request only sends persistent attributes because the api is ignorant of the user interface. When the response comes back you can find the original object by its previously established ID and handle it accordingly. If successful, you'd likely do nothing that the user sees. However, if you hadn't given it an ID, it would be discarded and recreated from the object in the response. This response object would not have all the transient attributes of the object in the request. So, for example, if its location on the screen were a transient attribute, then the user would see it jump to a default location since the former location would be lost.

Any other questions? Just ask.

See any mistakes? Help improve this data