hackboard

To start make sure you have run yarn install (just once) and then execute following commands:

mvnw spring-boot:run: (runs the backend)
yarn start: (runs the frontend)

Committing

Each commit must have an associated Issue on Github. The issue number must be included as reference in each commit message at the beginning.

The format is: #[issue number]: [text]. For example a commit message for issue number 20 would be formatted like:

#20: created and entity

In order to make this work, we are using the npm library commit-message-validator which is part of the devDependencies in package.json. Together with the npm library husky which can execute git hooks it runs on each commit. The rules can be found under the property config.commit-message-validator in package.json.

Coding Styles

Rules for coding styles are only required for the backend and is handled by the modules prettier and tslint.

TSLint checks the typescript code for certain rules and fails the build if it finds a violation.

Prettier behaves differently. It automatically formats _.ts, _.json, and *.css files before they are committed. This is done by using the same pattern we find in the commit-message-validator: Via git hooks and husky.

Prettier is automatically called by husky via the script precommit and only applies to file that are staged.

Swagger

Since it is duplicated and errorprone work to maintain endpoints we are using a code generator Swagger. Swagger works with a central configuration file which is stored in src/main/resources/swagger/api.yml There we define all endpoints with their response and request types.

The code generator itself is a maven plugin and is executed at each compile phase.

Swagger Backend

The generated backend-code is Spring compatible and consists of Interfaces that have the endpoints defined as methods and contain already the required Spring Annotations like @RestController or @RequestMapping. What's left is to implement these interfaces. Response and Request types are also automatically created and updated for us.

The interfaces are stored in io.refugeescode.hackboard.web.api.controller, the request and response types in io.refugeescode.hackboard.service.dto.

Swagger Frontend

Additionally to the generated backend code, Swagger also generates the code for Angular at each compile phase via maven. The Angular code is an own module called api and can be found in src/main/webapp/app/api.

Each endpoint is represented by an Angular service that can be injected. Internally it works with the default Angular http module and returns an Observable.

What follows is the documentation generated by JHipster.

Service workers

Service workers are commented by default, to enable them please uncomment the following code.

The service worker registering script in index.html

<script>
    if ('serviceWorker' in navigator) {
        navigator.serviceWorker
        .register('./sw.js')
        .then(function() { console.log('Service Worker Registered'); });
    }
</script>

Note: workbox creates the respective service worker and dynamically generate the sw.js

Managing dependencies

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.

Using angular-cli

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

Building for production

To optimize the hackboard 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:8080 in your browser.

Refer to Using JHipster in production for more details.

Testing

To launch your application's tests, run:

./mvnw clean test

Client tests

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

yarn test

For more information, refer to the Running tests page.

Using Docker to simplify development (optional)

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 mysql database in a docker container, run:

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

To stop it and remove the container, run:

docker-compose -f src/main/docker/mysql.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 verify -Pprod dockerfile: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 (jhipster docker-compose), which is able to generate docker configurations for one or several JHipster applications.

Continuous Integration (optional)

To configure CI for your project, run the ci-cd sub-generator (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.

ImgBotApp / hackboard