vormiaphp/vormiaguardjs

Laravel Sanctum-compatible frontend access control for React, Vue, Svelte, Qwik, Astro, and Solid.

VormiaGuardJS is designed to work seamlessly with Laravel backends, but secure access control requires backend support for:

• Authenticated user info (/api/user)
• Role and permission checks
• Backend-driven access control (/api/can-access)
• Guard/role middleware

VormiaGuardPHP is the official Laravel backend package that provides these endpoints and middleware. It ensures your frontend and backend are fully integrated for secure, role-based access control. If you use VormiaGuardJS with Laravel, install VormiaGuardPHP for best results.

Laravel Users: If you are using Laravel, check out the official VormiaGuard PHP package for backend integration:

• Maintains Laravel session via Sanctum (cookies)
• Authenticated user state (GET /api/user)
• Route/component-level access control (roles, user presence)
• SPA (React Router) and MPA (SEO-friendly) support
• Uses VormiaQueryJS for all API calls

For backend setup, route registration, and middleware configuration, see the VormiaGuardPHP README for complete instructions.

For full documentation and usage examples, visit:

• GitHub Repository
• Packagist Package

Installation

Install VormiaGuardJS and its peer dependencies:

npm install vormiaguardjs
npm install vormiaqueryjs
npm install zustand

Note:

• vormiaqueryjs is a required peer dependency.
• This package uses Zustand for state management.

Quick Start (React SPA)

import { createVormiaClient, createGuardClient } from "vormiaguardjs";

// 1. Setup VormiaQueryJS client
createVormiaClient({ baseURL: "http://localhost", withCredentials: true });

// 2. Setup VormiaGuardJS client
createGuardClient({
  apiBaseUrl: "http://localhost",
  mode: "spa", // or 'mpa'
  redirects: { onFail: "/login", onSuccess: "/" },
});

Protecting Routes (React)

import { VrmGuard } from "vormiaguardjs";

<VrmGuard roles={["admin"]} redirectTo="/login">
  <AdminDashboard />
</VrmGuard>;

Login/Logout Hooks (React)

import { useVrmLogin, useVrmLogout } from "vormiaguardjs";

const { login, isLoading, error } = useVrmLogin({ redirectTo: "/" });
const { logout } = useVrmLogout({ redirectTo: "/login" });

Multi-Framework Usage

Note: All main exports are available at the root of the package. If you need framework-specific adapters and they are not available at the root, check the documentation or request their export in future releases.

Vue

import { useVormiaGuard } from "vormiaguardjs";
const { user, isLoading, isAuthenticated } = useVormiaGuard();

Svelte

import { createVormiaGuardStore } from "vormiaguardjs";
const { user, isAuthenticated } = createVormiaGuardStore();

Qwik

import { useVormiaGuard } from "vormiaguardjs";
const { user, isAuthenticated } = useVormiaGuard();

Astro

import { useVormiaGuard } from "vormiaguardjs";
const { user, isAuthenticated } = useVormiaGuard();

Solid

import { createVormiaGuardResource } from "vormiaguardjs";
const [user, { isAuthenticated }] = createVormiaGuardResource();

Configuration

• apiBaseUrl: Laravel API base URL
• mode: 'spa' (React Router) or 'mpa' (window.location)
• redirects: { onFail, onSuccess } for login/logout

Example: Login Page (React)

import { useVrmLogin } from "vormiaguardjs";

function LoginPage() {
  const { login, isLoading, error } = useVrmLogin({ redirectTo: "/" });
  const handleSubmit = (e) => {
    e.preventDefault();
    const form = e.target;
    login({
      email: form.email.value,
      password: form.password.value,
    });
  };
  return (
    <form onSubmit={handleSubmit}>
      <input name="email" />
      <input name="password" type="password" />
      <button type="submit" disabled={isLoading}>
        Login
      </button>
      {error && <div>{error.message}</div>}
    </form>
  );
}

Auth Store (Zustand)

import { useVrmAuthStore } from "vormiaguardjs";
const user = useVrmAuthStore((s) => s.user);

For Laravel + React Developers

• No boilerplate for Sanctum session, user state, or role checks
• Works with any Laravel backend using Sanctum
• Not a form manager or UI library: just session, role, and access logic

Example Usage

See runnable example projects:

• SPA Example (React)
• MPA Example (HTML/JS)

Single Page Application (SPA)

import { useVrmGuard } from "vormiaguardjs";

function App() {
  const { isAuthenticated, user, login, logout } = useVrmGuard();

  return (
    <div style={{ padding: 32, fontFamily: "sans-serif" }}>
      <h1>VormiaGuardJS SPA Example</h1>
      {isAuthenticated ? (
        <>
          <p>Welcome, {user.name}!</p>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <button onClick={login}>Login</button>
      )}
    </div>
  );
}

Multi Page Application (MPA)

import { GuardClient } from "vormiaguardjs";

const guard = new GuardClient({
  endpoint: "/api/auth",
});

if (guard.isAuthenticated()) {
  // Render protected content
  document.getElementById("app").innerHTML = `Welcome, ${
    guard.getUser().name
  }! <button id="logout">Logout</button>`;
  document.getElementById("logout").onclick = () => guard.logout();
} else {
  // Render login button
  document.getElementById("app").innerHTML =
    '<button id="login">Login</button>';
  document.getElementById("login").onclick = () => guard.login();
}

License

MIT License

Copyright (c) 2025 Vormia