{"id":16616,"library":"decap-cms-ui-auth","title":"Decap CMS UI Authentication Components","description":"decap-cms-ui-auth is a specialized UI library providing the interactive authentication components for Decap CMS, an open-source content management system. Currently at version 3.3.0, it is an actively maintained package within the broader Decap CMS project, which follows a frequent release cadence, often seeing multiple patch and minor updates within weeks. This package is distinct from `decap-cms-lib-auth`, which handles the underlying authentication logic; `decap-cms-ui-auth` focuses solely on rendering the user interface for login, logout, and related authentication flows. It leverages React and Emotion for its component architecture and styling, ensuring a consistent look and feel with other Decap CMS UI elements. Its key differentiator is its tight integration with the Decap CMS ecosystem, making it the canonical choice for building custom Decap CMS admin interfaces that require authentication.","status":"active","version":"3.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/decaporg/decap-cms/tree/main/packages/decap-cms-ui-auth","tags":["javascript","decap-cms","ui","auth"],"install":[{"cmd":"npm install decap-cms-ui-auth","lang":"bash","label":"npm"},{"cmd":"yarn add decap-cms-ui-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add decap-cms-ui-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Styling solution for React components","package":"@emotion/react","optional":false},{"reason":"Styling solution for React components","package":"@emotion/styled","optional":false},{"reason":"Provides core authentication logic and authenticator instances consumed by the UI components","package":"decap-cms-lib-auth","optional":false},{"reason":"Provides default UI components and styling conventions","package":"decap-cms-ui-default","optional":false},{"reason":"Utility belt library, commonly used across Decap CMS packages","package":"lodash","optional":false},{"reason":"Runtime type checking for React props","package":"prop-types","optional":false},{"reason":"Core library for building user interfaces","package":"react","optional":false}],"imports":[{"note":"AuthPage is the primary component for rendering the CMS login interface. CommonJS require() syntax is generally incompatible since v3.","wrong":"const AuthPage = require('decap-cms-ui-auth').AuthPage;","symbol":"AuthPage","correct":"import { AuthPage } from 'decap-cms-ui-auth';"},{"note":"Another named export component for authentication. Ensure named import syntax.","wrong":"import AuthenticationPage from 'decap-cms-ui-auth/AuthenticationPage';","symbol":"AuthenticationPage","correct":"import { AuthenticationPage } from 'decap-cms-ui-auth';"},{"note":"The core authenticator logic is provided by 'decap-cms-lib-auth', not 'decap-cms-ui-auth'. 'decap-cms-ui-auth' consumes an 'authenticator' instance via props.","wrong":"import { authenticator } from 'decap-cms-ui-auth';","symbol":"Authenticator (via decap-cms-lib-auth)","correct":"import { authenticator } from 'decap-cms-lib-auth';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { AuthPage } from 'decap-cms-ui-auth';\n// In a real application, you would initialize 'authenticator' from 'decap-cms-lib-auth'.\n// For this quickstart, we'll use a mock object.\n\n// Mock authenticator - in production, replace with a properly initialized instance from 'decap-cms-lib-auth'\nconst mockAuthenticator = {\n  authenticate: async (credentials) => {\n    console.log('Attempting authentication with:', credentials);\n    return { token: 'mock-token', user: { name: 'Mock User' } };\n  },\n  clear: () => console.log('Authenticator cleared'),\n  retrieve: async () => ({ token: 'mock-token', user: { name: 'Mock User' } }),\n  // Add other methods expected by AuthPage (e.g., 'authProviders')\n  authProviders: [], // No providers for this mock\n};\n\nfunction MyAuthApp() {\n  const handleLoginSuccess = (user) => {\n    console.log('Login successful!', user);\n    alert(`Welcome, ${user.name}!`);\n    // Typically, you'd redirect to the CMS dashboard here\n  };\n\n  const handleLoginError = (error) => {\n    console.error('Login error:', error.message);\n    alert(`Login failed: ${error.message}`);\n  };\n\n  return (\n    <div style={{ fontFamily: 'sans-serif', textAlign: 'center', marginTop: '50px' }}>\n      <h1>Welcome to Decap CMS</h1>\n      <p>Please log in to manage your content.</p>\n      <div style={{\n        maxWidth: '400px', margin: '20px auto', padding: '20px',\n        border: '1px solid #eee', borderRadius: '8px',\n        boxShadow: '0 2px 10px rgba(0,0,0,0.05)'\n      }}>\n        <AuthPage\n          authenticator={mockAuthenticator}\n          onLogin={handleLoginSuccess}\n          onError={handleLoginError}\n          inProgress={false} // Set to true during an active login attempt\n          config={{ backend: { name: 'git-gateway' } }} // Minimal config prop, AuthPage might inspect it\n          logoURL=\"https://decapcms.org/img/decap-logo.svg\" // Optional: path to your CMS logo\n        />\n      </div>\n    </div>\n  );\n}\n\n// To run this example:\n// Ensure you have a 'root' div in your HTML file (e.g., <div id=\"root\"></div>)\nconst root = ReactDOM.createRoot(document.getElementById('root'));\nroot.render(<MyAuthApp />);\n","lang":"typescript","description":"This quickstart demonstrates how to render the `AuthPage` component, illustrating its basic props for an `authenticator` instance and callback handlers for login success and errors. It uses a mock authenticator for standalone demonstration."},"warnings":[{"fix":"Update package names in `package.json` and all import paths in your codebase (e.g., `import { AuthPage } from 'decap-cms-ui-auth';`).","message":"The entire Netlify CMS project was renamed to Decap CMS starting with version 3.x. This package's name changed from `netlify-cms-ui-auth` to `decap-cms-ui-auth`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your project uses ES Modules (e.g., `\"type\": \"module\"` in `package.json` or configuring bundlers like Webpack/Rollup for ESM). Use `import` statements instead of `require()`.","message":"Decap CMS version 3.x and its associated packages, including `decap-cms-ui-auth`, are primarily designed for ES Module (ESM) environments. Direct `require()` calls for CommonJS might lead to errors.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Check your `package.json` and ensure all listed peer dependencies are installed with compatible versions. For example: `npm install react@^19.1.0 @emotion/react@^11.11.1 decap-cms-lib-auth@^3.0.0`.","message":"`decap-cms-ui-auth` relies heavily on peer dependencies, including `react`, `@emotion/react`, `decap-cms-lib-auth`, and `decap-cms-ui-default`. These must be explicitly installed in your project.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade your project's React version to `^19.1.0` or ensure compatibility if using a newer React minor version. Downgrading `decap-cms-ui-auth` to a version compatible with your React version may also be an option if React 19 is not feasible.","message":"The `react` peer dependency for `decap-cms-ui-auth@3.3.0` is `^19.1.0`. Using older React versions (e.g., React 17 or 18) might lead to incompatibility warnings or runtime errors.","severity":"breaking","affected_versions":"3.3.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install decap-cms-ui-auth` or `yarn add decap-cms-ui-auth`. Ensure all import statements use the correct package name.","cause":"The package `decap-cms-ui-auth` is not installed or the import path is incorrect after the renaming from Netlify CMS.","error":"Module not found: Error: Can't resolve 'decap-cms-ui-auth'"},{"fix":"Ensure you correctly import and initialize `authenticator` from `decap-cms-lib-auth` and pass it as a prop: `<AuthPage authenticator={authenticatorInstance} />`.","cause":"The `authenticator` prop passed to `AuthPage` is either missing, `undefined`, or does not have the expected methods from `decap-cms-lib-auth`.","error":"TypeError: Cannot read properties of undefined (reading 'authenticate') (in <AuthPage component>)"},{"fix":"Verify that your `react` and `react-dom` versions in `package.json` satisfy the peer dependency requirements of `decap-cms-ui-auth` (currently `^19.1.0`). Upgrade or adjust versions as needed.","cause":"This often indicates a React version mismatch between your application's React and what `decap-cms-ui-auth` expects (e.g., trying to run with React 18 when Decap CMS requires React 19).","error":"Invariant Violation: Minified React error #XXX; visit https://reactjs.org/docs/error-decoder.html?invariant=XXX for the full message or use the non-minified dev environment for full errors."},{"fix":"Ensure you are using named imports for components: `import { AuthPage } from 'decap-cms-ui-auth';`. If using CommonJS, consider migrating your project to ESM or finding an older, compatible version of Decap CMS.","cause":"Incorrect import syntax, often trying to use CommonJS `require()` with an ESM-only package or using `import AuthPage from '...' ` for a named export.","error":"AuthPage is not a function/component (or similar 'is not a constructor' error with CommonJS)"}],"ecosystem":"npm"}