Quick Start

Build a fully access-controlled app in under 5 minutes.

1. Define Your Config

Create a configuration that describes your roles, permissions, and features:

// access.config.ts
import { defineAccess } from "react-access-engine";

export const accessConfig = defineAccess({
  roles: ["admin", "editor", "viewer"] as const,

  permissions: {
    admin: ["*"], // superuser
    editor: ["posts:read", "posts:write", "posts:publish"],
    viewer: ["posts:read"],
  },

  features: {
    darkMode: { enabled: true },
    betaEditor: { enabled: true, allowedRoles: ["admin", "editor"] },
    newDashboard: { rolloutPercentage: 50 },
  },

  plans: ["free", "pro", "enterprise"] as const,
});

2. Wrap Your App

Provide the config and the current user to <AccessProvider>:

// App.tsx
import { AccessProvider } from "react-access-engine";
import { accessConfig } from "./access.config";

const currentUser = {
  id: "user-42",
  roles: ["editor"] as const,
  plan: "pro" as const,
  attributes: {
    department: "engineering",
    country: "US",
  },
};

function App() {
  return (
    <AccessProvider config={accessConfig} user={currentUser}>
      <Dashboard />
    </AccessProvider>
  );
}

3. Gate Your UI

Use declarative components to show/hide UI based on access:

import { Can, Feature, AccessGate } from "react-access-engine";

function Dashboard() {
  return (
    <div>
      {/* Permission check */}
      <Can permission="posts:write">
        <button>Create Post</button>
      </Can>

      {/* Feature flag */}
      <Feature name="betaEditor" fallback={<ClassicEditor />}>
        <BetaEditor />
      </Feature>

      {/* Multi-condition gate */}
      <AccessGate permission="posts:publish" plan="pro">
        <PublishButton />
      </AccessGate>
    </div>
  );
}

4. Use Hooks for Logic

For programmatic checks, use the hooks:

import {
  usePermission,
  useFeature,
  useRole,
  usePlan,
} from "react-access-engine";

function PostActions() {
  const canWrite = usePermission("posts:write");
  const { enabled: hasBetaEditor } = useFeature("betaEditor");
  const { hasRole } = useRole();
  const { hasPlanAccess } = usePlan();

  return (
    <div>
      {canWrite && <button>Edit</button>}
      {hasRole("admin") && <button>Delete</button>}
      {hasPlanAccess("enterprise") && <button>Bulk Export</button>}
    </div>
  );
}

5. Add DevTools (Optional)

Drop in the devtools overlay for debugging during development:

import { AccessDevtools } from "react-access-engine-devtools";

function App() {
  return (
    <AccessProvider config={accessConfig} user={currentUser}>
      <Dashboard />
      {process.env.NODE_ENV === "development" && <AccessDevtools />}
    </AccessProvider>
  );
}

What's Next?