{"id":16781,"library":"blade-auth","title":"Blade Authentication Utilities","description":"The `blade-auth` package provides essential utility functions and helpers designed for integrating authentication services seamlessly into applications built with the Blade framework. As of version 3.29.10, it offers streamlined mechanisms for common authentication patterns, including user registration, sign-in, sign-out, and active session management. The package maintains a relatively frequent release cadence, with recent updates focusing on refining internal 'trigger' syntax, improving documentation accuracy, and enhancing developer experience through features like dependency override support in the build API and improved error handling. Its primary differentiation lies in its deep integration within the Blade ecosystem, aiming to abstract away common authentication complexities and provide a consistent experience aligned with the Blade architectural philosophy. It targets modern JavaScript environments, likely favoring ESM.","status":"active","version":"3.29.10","language":"javascript","source_language":"en","source_url":"https://github.com/ronin-co/blade","tags":["javascript","blade","auth"],"install":[{"cmd":"npm install blade-auth","lang":"bash","label":"npm"},{"cmd":"yarn add blade-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add blade-auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Most Blade packages are ESM-first. Use named imports for core utilities.","wrong":"const initAuth = require('blade-auth').initAuth;","symbol":"initAuth","correct":"import { initAuth } from 'blade-auth';"},{"note":"Authentication actions like `signIn` are typically named exports from the main package entry point.","wrong":"import signIn from 'blade-auth/signIn';","symbol":"signIn","correct":"import { signIn } from 'blade-auth';"},{"note":"For retrieving the current authentication state or session, `getAuthSession` is a common named export.","wrong":"const { getAuthSession } = require('blade-auth');","symbol":"getAuthSession","correct":"import { getAuthSession } from 'blade-auth';"}],"quickstart":{"code":"import { initAuth, signIn, signUp, signOut, getAuthSession } from 'blade-auth';\n\ninterface AuthConfig {\n  apiBaseUrl: string;\n  jwtSecret: string;\n}\n\ninterface UserCredentials {\n  email: string;\n  password: string;\n}\n\nasync function runAuthFlow() {\n  // Initialize auth with configuration\n  const config: AuthConfig = {\n    apiBaseUrl: process.env.BLADE_API_URL ?? 'https://api.example.com/v1',\n    jwtSecret: process.env.BLADE_JWT_SECRET ?? 'super-secret-key-please-change'\n  };\n  \n  // In a real app, this would be configured once, likely on app start\n  initAuth(config);\n\n  const user: UserCredentials = {\n    email: 'test@example.com',\n    password: 'password123'\n  };\n\n  try {\n    console.log('Attempting to sign up...');\n    const signUpResult = await signUp(user.email, user.password);\n    console.log('Sign up successful:', signUpResult);\n\n    console.log('Attempting to sign in...');\n    const signInResult = await signIn(user.email, user.password);\n    console.log('Sign in successful:', signInResult);\n\n    console.log('Getting current auth session...');\n    const session = await getAuthSession();\n    console.log('Current session:', session);\n\n    if (session?.isAuthenticated) {\n      console.log('User is authenticated. Token:', session.token);\n    }\n\n    console.log('Attempting to sign out...');\n    await signOut();\n    console.log('Sign out successful.');\n\n    const postSignOutSession = await getAuthSession();\n    console.log('Session after sign out:', postSignOutSession);\n\n  } catch (error) {\n    console.error('Authentication error:', error);\n  }\n}\n\nrunAuthFlow();","lang":"typescript","description":"This quickstart demonstrates the initialization of `blade-auth`, a user signup and sign-in flow, retrieving the current session, and finally signing out."},"warnings":[{"fix":"Review the official Blade documentation for the updated trigger syntax introduced in 3.29.0 and refactor existing trigger configurations accordingly. Pay close attention to how triggers are declared and loaded.","message":"Version 3.29.0 introduced a 'simplified trigger syntax' which updated auth logic and likely renders previous trigger configurations incompatible. Applications upgrading from earlier 3.x versions will need to adapt their trigger definitions.","severity":"breaking","affected_versions":">=3.29.0"},{"fix":"Standardize all trigger names and references to use kebab-case (e.g., `my-auth-trigger` instead of `myAuthTrigger`).","message":"When defining or referencing triggers, ensure they are consistently kebab-cased. Version 3.29.8 explicitly documented this convention, suggesting it's important for correct functionality.","severity":"gotcha","affected_versions":">=3.29.8"},{"fix":"Ensure your project is a Blade application and `blade-auth` is integrated as intended by the framework's documentation. Avoid standalone usage without understanding its dependencies on the Blade runtime.","message":"This library is primarily built for the Blade ecosystem. Attempting to use `blade-auth` outside of a properly configured Blade application context might lead to unexpected behavior or require significant manual setup not covered by its utilities.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update your trigger definitions to comply with the simplified trigger syntax introduced in `blade-auth` v3.29.0. Consult the latest Blade documentation for examples.","cause":"Attempting to use pre-3.29.0 trigger syntax after upgrading to version 3.29.0 or later.","error":"Error: Invalid trigger syntax provided."},{"fix":"Always check if the session object returned by `getAuthSession()` is defined and its properties (like `isAuthenticated`) exist before accessing them. Ensure `initAuth` is called before any other auth operations.","cause":"The `getAuthSession()` function returned `null` or `undefined` because the user is not logged in or the authentication service is not initialized correctly.","error":"TypeError: Cannot read properties of undefined (reading 'isAuthenticated')"},{"fix":"Double-check the provided credentials. If this error persists, investigate the server-side authentication logs or ensure the `apiBaseUrl` provided to `initAuth` points to the correct authentication endpoint.","cause":"The username or password provided to `signIn` or `signUp` did not match records on the authentication server.","error":"AuthError: Invalid credentials."}],"ecosystem":"npm","meta_description":null}