This Node.js SDK provides seamless integration with an Authula server for both client-side and server-side applications and is framework agnostic.

---

Features

• Framework Agnostic: Works with Next.js/React, Vue.js and more
• Full TypeScript Support: Complete TypeScript definitions with strict typing
• CSRF Protection: Automatic CSRF token handling for mutating requests
• Multiple Auth Methods: Email/password, OAuth2, JWT-based authentication
• Plugin Architecture: Extensible plugin system for custom authentication flows
• Automatic Token Refresh: Built-in bearer token refresh mechanism
• Built-in support for Zod and Tanstack Query: provides types and zod schemas out of the box along with tanstack query code for all available methods.

Installation

npm install authula
# or
yarn add authula
# or
pnpm add authula

Quick Start

Basic Setup

Client instance:

Use with SPA (Vite etc.)

import { createClient } from "authula";
import { CorePlugin, EmailPasswordPlugin } from "authula/plugins";

const authulaBrowserClient = createClient({
  // Your Authula server URL
  url: "http://localhost:8080/api/auth",
  plugins: [new CorePlugin(), new EmailPasswordPlugin()],
});

// Direct method call
const response = await authulaBrowserClient.core.getMe();

// Tanstack Query
const { data, error, isLoading, isError } =
  await authulaBrowserClient.core.useGetMe();

Server instance:

Use with SSR frameworks e.g. Next.js/Tanstack Start etc.

import { cookies } from "next/headers";

import { createClient } from "authula";
import { CorePlugin, EmailPasswordPlugin } from "authula/plugins";

const authulaServerClient = createClient({
  // Your Authula server URL
  url: "http://localhost:8080/api/auth",
  plugins: [new CorePlugin(), new EmailPasswordPlugin()],
  // For frameworks other than Next.js, you may need to implement this cookies object manually by implementing the interface.
  cookies: cookies,
});

// Now you can use the client...

const response = await authulaServerClient.core.getMe();

Available Plugins

The following plugins are available in this SDK:

• Core
• Access Control
• Admin
• Organizations
• API Key
• Email Password
• OAuth2
• CSRF
• JWT
• Bearer
• Magic Link
• TOTP

Advanced Configuration

Fetch Options

Configure fetch behavior with timeout and other options:

const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  fetchOptions: {
    abortTimeout: 30, // Timeout in seconds
    headers: {}, // Custom headers
  },
  plugins: [
    // your plugins
  ],
});

Custom Hooks

Add custom before/after fetch hooks for advanced customization:

const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  plugins: [new CorePlugin()],
});

// Register a before fetch hook
authulaClient.registerBeforeFetch(async (ctx) => {
  console.log(`Making request to: ${ctx.url}`);
  // Modify context if needed
  ctx.init.headers = {
    ...ctx.init.headers,
    "X-Custom-Header": "value",
  };
});

// Register an after fetch hook
authulaClient.registerAfterFetch(async (ctx, response) => {
  console.log(`Received response: ${response.status}`);
  if (response.status >= 400) {
    // Handle error
  }
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.