Tutorial: Build a TideCloak + React.js App from Scratch

This tutorial walks you through setting up the TideCloak SDK in a React application to handle secure authentication.

---

1) Prepare TideCloak

• Ensure your realm is set up (you can use the dev container in the other tutorial).
• In the Admin Console, go to Clients → myclient → Action → Download adaptor configs (format: keycloak-oidc-keycloak-json).
• Save the JSON in your app (e.g., /tidecloakAdapter.json).

---

2) Create your React JS project

Note: You can find deep dives on the provider props, hook return values, TypeScript types, and more in the TideCloak React SDK docs.

a. Create a React app using Vite

Run the following commands to create a new React app using Vite:

npm create vite@latest tidecloak-react -- --template react-ts
cd tidecloak-react
npm install @tidecloak/react

b. Export your TideCloak adapter

Export your specific TideCloak settings and hardcode it in your project:

1. Go to your Clients menu → mytest client ID
2. Update Valid redirect URIs to http://localhost:5173/*
3. Update Web origins to http://localhost:5173
4. In your Clients menu → mytest client ID → Action dropdown → Download adaptor configs option (keep it as keycloak-oidc-keycloak-json format)
5. Download or copy the details of that config and paste it in your project's root folder under tidecloak.json.

c. nano src/main.tsx

Make the following changes:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
- import App from './App.tsx'
+ import { TideCloakContextProvider, useTideCloak, Authenticated, Unauthenticated } from '@tidecloak/react'
+ import tidecloakConfig from "../tidecloak.json"
+
+ function UserInfo() {
+   const { logout, getValueFromIdToken, hasRealmRole } = useTideCloak();
+   const IsAllowedToViewProfile = () => (hasRealmRole("default-roles-myrealm") ? "Yes" : "No");
+
+   return (
+     <div>
+       <p>Signed in as <b>{getValueFromIdToken("preferred_username") ?? '…'}</b></p>
+       <p>Has Default Roles? <b>{IsAllowedToViewProfile()}</b></p>
+       <button onClick={logout}>Logout</button>
+     </div>
+   );
+  }
+
+ function Welcome() {
+   const { login } = useTideCloak();
+   return (
+     <div>
+       <h1>Hello!</h1>
+       <p>Please authenticate yourself!</p>
+       <p><button onClick={login}>Login</button></p>
+     </div>
+   );
+ }
+
 createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <TideCloakContextProvider config={tidecloakConfig}>
+      <Authenticated>
+        <UserInfo/>
+      </Authenticated>
+      <Unauthenticated>
+        <Welcome/>
+      </Unauthenticated>
+    </TideCloakContextProvider>
-    <App />
  </StrictMode>,
)

So it looks like this:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import { TideCloakContextProvider, useTideCloak, Authenticated, Unauthenticated } from '@tidecloak/react'
import tidecloakConfig from "../tidecloak.json"

function UserInfo() {
  const { logout, getValueFromIdToken, hasRealmRole } = useTideCloak();
  const IsAllowedToViewProfile = () => (hasRealmRole("default-roles-myrealm") ? "Yes" : "No");

  return (
    <div>
      <p>Signed in as <b>{getValueFromIdToken("preferred_username") ?? '…'}</b></p>
      <p>Has Default Roles? <b>{IsAllowedToViewProfile()}</b></p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

function Welcome() {
  const { login } = useTideCloak();
  return (
    <div>
      <h1>Hello!</h1>
      <p>Please authenticate yourself!</p>
      <p><button onClick={login}>Login</button></p>
    </div>
  );
}

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <TideCloakContextProvider config={tidecloakConfig}>
      <Authenticated>
        <UserInfo/>
      </Authenticated>
      <Unauthenticated>
        <Welcome/>
      </Unauthenticated>
    </TideCloakContextProvider>
  </StrictMode>,
)

---

3) Build your NPM environment

Download and install all the dependencies for this project:

npm install

---

4. Run your project

Build and run your project:

npm run dev

All done!

---

5) Play!

1. Go to http://localhost:5173 You should see a "Hello!" message.
2. Click on the Login button
3. Click on Create an account
4. Provide a new username, password, recovery email(s)

It will now show you that you're "Signed in" and it will show you your anonymous Tide username for this app.

---

Project recap

Let's review what just happened and what you've just accomplished:

1. You have programmed, compiled, built and deployed, from the ground-up, a fully-functional ReactJS Single-Page-Application (SPA).
2. Web users can now sign up and sign in to your SPA, being served customized content to authenticated and unauthenticated users and based on their predefined roles.
3. Your web users' roles and permissions are managed locally on your very own self-hosted instance of TideCloak - one of the most robust, powerful and feature-rich Identity and Access Management system which you have downloaded, installed, configured and deployed locally.
4. Your web users enjoy fully-secured Tide accounts, with their identity and access-credentials sitting outside of anyone's reach.
5. Your TideCloak instance is secured by the global Tide Cybersecurity Fabric that you have activated and licensed.

---

What next?

There are two additional layers of protection you can configure through TideCloak:

1. Identity Governance: Establish workflow processes ensuring that no compromised administrator can cause damage.
2. User walletization: Ability to lock user data with unique user keys secured by Tide's Cybersecurity Fabric - so ownership and privacy can be guaranteed.

---