Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
This Node.js SDK provides seamless integration with an Authula server for both client-side and server-side applications and is framework agnostic.
- 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.
npm install authula
# or
yarn add authula
# or
pnpm add authulaClient 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();The following plugins are available in this SDK:
- Core
- Access Control
- Admin
- Organizations
- API Key
- Email Password
- OAuth2
- CSRF
- JWT
- Bearer
- Magic Link
- TOTP
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
],
});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
}
});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.
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.