An Ionic Client for JHipster 🤓

March 30, 2023 · View on GitHub

Because Ionic Apps need some JHipster 💙 too!

Ionic JHipster

Table of Contents

  1. Getting Started
  2. Run on iOS
  3. Run on Android
  4. Use OpenID Connect for Authentication { Keycloak, Okta, or Auth0 }
  5. Services
  6. i18n (adding languages)
  7. Testing

Getting Started

To run this app:

npm install
# start the backend manually or run `npm run backend:start`
npm start

Run on iOS

Generate a native iOS project with the following commands:

npx ionic build
npx ionic capacitor add ios

Add dev.localhost.ionic as a custom scheme to ios/App/App/Info.plist. You can also use your reverse domain name.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.getcapacitor.capacitor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>capacitor</string>
      <string>dev.localhost.ionic</string>
      <!--string>com.okta.dev-133337</string-->
    </array>
  </dict>
</array>

Then, run your project using the Capacitor CLI:

npx cap run ios

Camera capacitor

When adding image fields, you need to add privacy notices to your ios/App/App/Info.plist.

    <key>NSCameraUsageDescription</key>
    <string>Privacy - Camera Usage Description</string>
    <key>NSPhotoLibraryAddUsageDescription</key>
    <string>Privacy - Photo Library Additions Usage Description</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>Privacy - Photo Library Usage Description</string>

For more information refer to @capacitor/camera

Modify CORS Settings in JHipster

In order to communicate with your JHipster app, you'll need to modify its CORS settings (in src/main/resources/config/application-dev.yml) make sure capacitor://localhost is allowed as an origin.

To run your app in iOS Simulator with hot-reload, run:

npx cap run ios -l --external

You will need to modify your JHipster app to allow your external IP as a trusted origin for this to work!

You can also open your project in Xcode and configure code signing.

npx cap open ios

Then, run your app from Xcode.

Run on Android

Generate a native project with the following commands:

npx ionic build
npx ionic capacitor add android

Enable clear text traffic and add dev.localhost.ionic as a scheme in android/app/src/main/AndroidManifest.xml (or use your reverse domain name):

<activity ... android:usesCleartextTraffic="true">
  <!-- You'll need to add this intent filter so redirects work -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="dev.localhost.ionic" />
    <!--data android:scheme="com.okta.dev-133337" /-->
  </intent-filter>

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>

Then, run your project using the Capacitor CLI:

npx cap run android

You'll need to run a couple commands to allow the emulator to communicate with JHipster (and Keycloak if you're using OIDC for authentication).

adb reverse tcp:8080 tcp:8080
adb reverse tcp:9080 tcp:9080

Modify CORS Settings in JHipster

In order to communicate with your JHipster app, you'll need to modify its CORS settings (in src/main/resources/config/application-dev.yml) to allow http://localhost as an origin.

To run your app in iOS Simulator with hot-reload, run:

npx cap run android -l --external

You will need to modify your JHipster app to allow your external IP as a trusted origin for this to work!

You can also open your project in Android Studio and run your app.

npx cap open android

Use OpenID Connect for Authentication

Choosing OAuth 2.0 / OIDC for authentication will allow you to use Keycloak or Okta for identity. In theory, you should be able to use any OIDC-compliant identity provider, and these are the only ones we've tested against. JHipster ships with Keycloak configured and ready to go by default. You simply have to start it in your JHipster backend.

docker-compose -f src/main/docker/keycloak up -d

Use Okta

See JHipster's Okta Guide to see how to configure JHipster for Okta. In addition to having an OIDC app for your JHipster backend, you'll need to create a Native app on Okta too.

Use Auth0

See JHipster's Auth0 Guide to see how to configure JHipster for Auth0. In addition to having an OIDC app for your JHipster backend, you'll need to create a Native app on Auth0 too.

Services

A generated Ionic for JHipster app comes with some basic implementations of common services.

User

The User service is used to authenticate users through its login(accountInfo) and signup(accountInfo) methods, which perform POST requests to an API endpoint that you will need to configure.

Api

The ApiService is a simple CRUD frontend to an API.

i18n

This app comes with internationalization (i18n) out of the box with ngx-translate. This makes it easy to change the text used in the app by modifying only one file.

Adding Languages

To add new languages, add new files to the src/assets/i18n directory, following the pattern of LANGCODE.json where LANGCODE is the language/locale code (ex: en/gb/de/es/etc.).

Testing

There are a number of scripts in package.json you can use to run tests:

"e2e": "ng e2e",
"e2e:ci": "ng run app:cypress-headless",
"e2e:open": "ng run app:cypress-open",
...
"test": "ng test --coverage",
"test:watch": "ng test --watch",
"cypress:open": "cypress open",
"cypress:run": "cypress run"

Unit Tests

Jest is used as the unit test runner in this project. Jest is a complete and easy to set-up JavaScript testing solution created by Facebook. Some of its benefits are:

  • Fast and sandboxed
  • Built-in code coverage reports
  • Zero configuration

To run all your unit tests:

npm test

A test coverage report will be created at public/coverage/lcov-report/index.html.

Daniel created Ionic Mocks with Jest Support by forking the ionic-mocks ionic-mock repository. There are still some issues. Feel free to help him out with his ionic-mocks-jest repository.

If you want to add ionic-native mocks you should definitely check out Chris Griffith's ionic-native-mocks repository

See a unit test example at src/app/app.component.spec.ts.

E2E Tests

The end-to-end (E2E) tests are powered by Cypress.

Add your tests in the cypress/e2e folder.

See the example end-to-end test in cypress/e2e/app.cy.ts.

To run the e2e tests:

npm run e2e