diva-auth-react v0.3.3

DIVA Auth React

DIVA Auth React ermöglicht die einfach Einbindung von UI Components, welche mit der DIVA Auth API interagieren. So kann mittels 2 einfacher Schritte Nutzerauthentifizierung zu jeder React basierenden DIVA App hinzugefügt werden.

Für die Verwendung in nicht-React Apps siehe Kapitel Verwendung in nicht-React Apps

Quick start

Installation

DIVA Auth React kann von NPM installiert werden:

npm i -S diva-auth-react

Verwendung

Hier ein Codebeispiel, wie Sie die DIVA Auth Komponenten in Ihre React App einbinden können.

Live Beispiel auf Codesandbox öffnen (Setzt voraus das die Production API verfügbar ist, funktioniert auch, wenn dazu eine localhost URL angegeben wurde).

import React from 'react';
import ReactDOM from 'react-dom';

import DivaAuthProvider, { useDivaAuth } from 'diva-auth-react';

function App() {
  const {
    actions: { toggleModal, logout },
    jwt,
    currentUser,
    loading,
  } = useDivaAuth();

  if (loading) return <span>Lädt...</span>;

  const greeting = currentUser
    ? `Hallo, ${currentUser.name}!`
    : 'Bitte einloggen oder registrieren.';

  return (
    <div>
      <h1>{greeting}</h1>
      {currentUser ? (
        <>
          <button onClick={() => toggleModal('editUserData')}>
            Meine Daten
          </button>
          <button onClick={() => logout()}>Ausloggen</button>
        </>
      ) : (
        <>
          <button onClick={() => toggleModal('login')}>Einloggen</button>
          <button onClick={() => toggleModal('register')}>Registrieren</button>
        </>
      )}
    </div>
  );
}

ReactDOM.render(
  <DivaAuthProvider
    divaAuthApiUrl="http://localhost:3000"
    urlToTOS="https://www.example.com/"
  >
    <App />
  </DivaAuthProvider>,
  document.querySelector('#root'),
);

Erklärung:

Zu Beginn müssen Sie Ihre Haupt-Komponente (im Beispiel <App />) in die <DivaAuthProvider /> Komponente geben. Nur so können die nötigen Funktionalitäten verwendet werden. Optional kann die API URL mit der Property divaAuthApiUrl angeben werden. Dies überschreibt den default Wert der Library. Mit der Property urlToTOS kann die URL zu den AGBs angegeben werden.

Nun können Sie überall in Ihrer React App die Hook useDivaAuth verwenden, welche als das Herzstück dieser Library gesehen werden kann: Mit ihr können Sie auf die Daten des eingeloggten Nutzers (jwt, currentUser) zugreifen und das UI steuern (toggleModal). Das JWT können Sie verwenden, um Requests zu der DIVA Auth API oder anderen DIVA APIs zu machen.

Entwicklung der Library

Diese Libary verwenden für das Design Emotion und für die Interaktion mit der DIVA Auth Rest API Restful React.

Dank Restful React kann aus der Open API Spezifikation automatisch ein React API Client erstellt werden. Um diesen zu generieren, führen Sie Folgendes im Basisverzeichnis aus:

npm run generate-api-client

Dies erstellt under components/api/index.tsx einen React API Client. Dieser Schritt sollte bei jeder Änderung der API durchgeführt werden, um einen aktuellen Client zu erstellen.

Anmerkung: Wegen eines Bugs in Restful React werden einige Typen nicht richtig erstellt, weshalb manuelle etwas nachgebessert werden muss, bis dieser Bug gefixed wurde (zur Zeit nur 3 Typen):

// Original:
export interface LoginResponse User & {token?: string}

// Ausgebessert:
export type LoginResponse = User & {token?: string}

// Original:
export interface RegisterUserResponse User & {token?: string}

// Ausgebessert:
export type RegisterUserResponse = User & {token?: string}

// Original:
export interface WhoAmIResponse User & {currentOrganization?: Organization}

// Ausgebessert:
export type WhoAmIResponse = User & {currentOrganization?: Organization}

Ich habe es zeitlich noch nicht geschafft eine Issue zu öffnen, das Problem wird durch erweiterte OpenAPI Schemas ausgelöst und sollte relativ einfach zu lösen sein.

Testen

Um die Library zu testen, kann einfach der lokale API Server und die Demo Frontend App gestartet werden:

npm run dev:api
npm run dev:frontend:demo

shared/config.ts

Die Konfigurationsvariable apiUrl in der Datei shared/config.ts wird in Production als API URL verwendet. Stellen Sie sicher, dass Sie immer auf die aktuelle DIVA Auth API zeigt.

Neue Version des NPM Packages veröffentlichen

Um Änderungen in der Library zu publizieren, muss folgendermaßen vorgegangen werden:

Schritt 1: Production build und TypeScript Typen erstellen:

npm run package:build

Dieser Command erstellt under components/dist einen Production Build der Library und die dazugehörigen TypeScript Typen.

Schritt 2: Version erhöhen

Um die Version des Packages zu erhöhen, folgendes ausführen:

cd components
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]

Schritt 3: Publizieren (Im Basisverzeichnis)

Dazu muss man als Owner des Packages hinzugefügt worden sein.

npm run package:publish

Verwendung in nicht-React Apps

Diese Library kann auch in nicht-React Apps (z.B. jQuery oder VanillaJS) verwendet werden. Dazu muss einfach die Library (welche unter components/dist/components/diva-auth.js) gefunden werden kann, mittels eines Standard script-Tags eingebunden werden.

Hier ein Code-Beispiel:

Achtung: React und ReactDOM müssen separat eingebunden werden, da diese nicht im Bundle enthalten sind. Siehe https://reactjs.org/docs/add-react-to-a-website.html für mehr Informationen dazu.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>DIVA Auth Test</title>
    <meta name="author" content="" />
    <meta name="description" content="" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <!-- React und React DOM einbinden. Siehe https://reactjs.org/docs/add-react-to-a-website.html
    für mehr Informationen dazu. -->
    <script
      src="https://unpkg.com/react@16/umd/react.development.js"
      crossorigin
    ></script>
    <script
      src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"
      crossorigin
    ></script>
    <!-- DIVA Auth library einbinden -->
    <script src="diva-auth.js"></script>
  </head>

  <body>
    <div id="diva-auth-container"></div>

    <script>
      setupDivaAuth({
        container: '#diva-auth-container',
        onSetup: data => {
          // Öffnet Login-Modal
          data.actions.toggleModal('login');
        },
        onDataChange: data => {
          // Daten haben sich geändert
          console.log('onchange', data);
        },
        props: {
          divaAuthApiUrl: 'http://localhost:3000',
          urlToTOS: 'https://www.example.com/',
        },
      });
    </script>
  </body>
</html>

Sobald die Library geladen wurde, kann die global Funktion setupDivaAuth aufgerufen werden. Es muss als erster und einziger Paramter ein Konfigurationsobjekt mit folgenden Properties übergeben werden:

• container: Ein Selector-String für das DOM Element, in welches DIVA Auth gerendert wird.
• onSetup: Funktion, welche zu Beginn einmal aufgerufen wird. Das übergebene data-Objekt ist das selbe Objekt, welches auch von der useDivaAuth-Hook zurückgegeben wird.
• onDataChange: Funktion, welche jedes Mal aufgerufen wird, wenn sich die Daten des Nutzers ändern. Das übergebene data-Objekt ist das selbe Objekt, welches auch von der useDivaAuth-Hook zurückgegeben wird. Achtung: In dieser Funktion dürfen keine actions ausgeführt werden, dies würde zu einer endlosen Render-Schleife führen.
• props: Properties, welche and die React Component DivaAuthProvider weitergegeben werden. Für mehr Informationen siehe die Dokumentation dieser Component.