KeycloakVue

A comprehensive Vue 3.5+ wrapper for keycloak-js using the Composition API. This library provides a seamless integration of Keycloak authentication into your Vue applications with full TypeScript support.

📚 Documentation

For complete documentation, examples, and API reference, visit:

📖 https://jefmari.github.io/keycloak-vue/

📋 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📦 Installation
• 🔧 Basic Usage
• 📚 Documentation
• 🔗 Links
• 🤝 Contributing
• 📄 License

✨ Features

• ✨ Vue 3.5+ Composition API - Built for modern Vue applications
• 🔒 Type-Safe - Full TypeScript definitions for all Keycloak types, props, and constants
• 🎯 Reactive State - Reactive authentication state using Vue's reactivity system
• 🔌 Plugin System - Easy integration with Vue's plugin system
• 🛡️ Vue Router Integration - Built-in support for route guards and authentication flows
• 🌐 IIFE Compatible - Supports older browsers without top-level await
• 🎨 Flexible - Use as a plugin or composable
• 📦 Tree-Shakeable - Import only what you need
• 🚀 SSO Ready - Full support for Single Sign-On features
• 🔄 Token Management - Automatic token refresh capabilities

🚀 Quick Start

Get started in just 2 steps:

1. Install the package

npm install keycloak-vue keycloak-js

2. Setup the plugin

// main.ts
import { createApp } from "vue";
import { createKeycloakPlugin } from "keycloak-vue";
import App from "./App.vue";

const app = createApp(App);

app.use(
  createKeycloakPlugin({
    config: {
      url: "https://your-keycloak-server",
      realm: "your-realm",
      clientId: "your-client-id",
    },
    initOptions: {
      onLoad: "login-required",
    },
  })
);

app.mount("#app");

3. Use in components

<script setup lang="ts">
import { useKeycloak } from "keycloak-vue";

const { isAuthenticated, username, login, logout } = useKeycloak();
</script>

<template>
  <div v-if="isAuthenticated">
    <p>Welcome, {{ username }}!</p>
    <button @click="logout()">Logout</button>
  </div>
  <div v-else>
    <button @click="login()">Login</button>
  </div>
</template>

That's it! 🎉

📦 Installation

npm install keycloak-vue keycloak-js

or

yarn add keycloak-vue keycloak-js

or

pnpm add keycloak-vue keycloak-js

🔧 Basic Usage

Plugin Setup (Recommended)

// main.ts
import { createApp } from "vue";
import { createKeycloakPlugin } from "keycloak-vue";
import App from "./App.vue";

const app = createApp(App);

app.use(
  createKeycloakPlugin({
    config: {
      url: "https://your-keycloak-server",
      realm: "your-realm",
      clientId: "your-client-id",
    },
    initOptions: {
      onLoad: "login-required",
      checkLoginIframe: false,
    },
  })
);

app.mount("#app");

Using the Composable

<script setup lang="ts">
import { useKeycloak } from "keycloak-vue";

const {
  isAuthenticated,
  isReady,
  username,
  token,
  login,
  logout,
  hasRealmRole,
} = useKeycloak();
</script>

<template>
  <div v-if="isReady">
    <div v-if="isAuthenticated">
      <p>Welcome, {{ username }}!</p>
      <button @click="logout()">Logout</button>

      <div v-if="hasRealmRole('admin')">
        <p>Admin content</p>
      </div>
    </div>
    <div v-else>
      <button @click="login()">Login</button>
    </div>
  </div>
  <div v-else>Loading...</div>
</template>

📚 Documentation

🌟 Complete Documentation Site

Our documentation includes:

• 📖 Getting Started Guide - Step-by-step setup
• ⚙️ Configuration - All configuration options
• 🎯 API Reference - Complete API documentation
• 💡 Examples - Real-world use cases
• 🔧 Advanced Usage - Manual initialization and more

Quick Links

| Topic | Description | Link | | --------------------- | ----------------------------- | ----------------------------------------------------------------------------- | | 🚀 Installation | How to install and setup | Guide | | 🔌 Plugin Setup | Vue plugin configuration | Guide | | 🎯 Composable | Using useKeycloak() | API | | 🔄 Token Refresh | Automatic token refresh | Example | | 🛡️ Protected APIs | Making authenticated requests | Example | | 👥 Role-Based Access | User roles and permissions | Example | | 🛣️ Router Integration | Vue Router guards | Guide |

🔗 Links

• 📖 Documentation - Complete documentation
• 📦 NPM Package - Package on NPM
• 🐙 GitHub Repository - Source code
• 🔐 Keycloak - Official Keycloak website
• 📘 Keycloak JS Adapter - Official JS adapter docs

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

Released under the MIT License.