Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AuthPage
✓ import { AuthPage } from 'decap-cms-ui-auth';
✗ const AuthPage = require('decap-cms-ui-auth').AuthPage;
AuthPage is the primary component for rendering the CMS login interface. CommonJS require() syntax is generally incompatible since v3.
AuthenticationPage
✓ import { AuthenticationPage } from 'decap-cms-ui-auth';
✗ import AuthenticationPage from 'decap-cms-ui-auth/AuthenticationPage';
Another named export component for authentication. Ensure named import syntax.
Authenticator (via decap-cms-lib-auth)
✓ import { authenticator } from 'decap-cms-lib-auth';
✗ import { authenticator } from 'decap-cms-ui-auth';
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.
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.
import React from 'react';
import ReactDOM from 'react-dom/client';
import { AuthPage } from 'decap-cms-ui-auth';
// In a real application, you would initialize 'authenticator' from 'decap-cms-lib-auth'.
// For this quickstart, we'll use a mock object.
// Mock authenticator - in production, replace with a properly initialized instance from 'decap-cms-lib-auth'
const mockAuthenticator = {
authenticate: async (credentials) => {
console.log('Attempting authentication with:', credentials);
return { token: 'mock-token', user: { name: 'Mock User' } };
},
clear: () => console.log('Authenticator cleared'),
retrieve: async () => ({ token: 'mock-token', user: { name: 'Mock User' } }),
// Add other methods expected by AuthPage (e.g., 'authProviders')
authProviders: [], // No providers for this mock
};
function MyAuthApp() {
const handleLoginSuccess = (user) => {
console.log('Login successful!', user);
alert(`Welcome, ${user.name}!`);
// Typically, you'd redirect to the CMS dashboard here
};
const handleLoginError = (error) => {
console.error('Login error:', error.message);
alert(`Login failed: ${error.message}`);
};
return (
<div style={{ fontFamily: 'sans-serif', textAlign: 'center', marginTop: '50px' }}>
<h1>Welcome to Decap CMS</h1>
<p>Please log in to manage your content.</p>
<div style={{
maxWidth: '400px', margin: '20px auto', padding: '20px',
border: '1px solid #eee', borderRadius: '8px',
boxShadow: '0 2px 10px rgba(0,0,0,0.05)'
}}>
<AuthPage
authenticator={mockAuthenticator}
onLogin={handleLoginSuccess}
onError={handleLoginError}
inProgress={false} // Set to true during an active login attempt
config={{ backend: { name: 'git-gateway' } }} // Minimal config prop, AuthPage might inspect it
logoURL="https://decapcms.org/img/decap-logo.svg" // Optional: path to your CMS logo
/>
</div>
</div>
);
}
// To run this example:
// Ensure you have a 'root' div in your HTML file (e.g., <div id="root"></div>)
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<MyAuthApp />);
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'decap-cms-ui-auth'
The package `decap-cms-ui-auth` is not installed or the import path is incorrect after the renaming from Netlify CMS.
fixRun `npm install decap-cms-ui-auth` or `yarn add decap-cms-ui-auth`. Ensure all import statements use the correct package name.
TypeError: Cannot read properties of undefined (reading 'authenticate') (in <AuthPage component>)
The `authenticator` prop passed to `AuthPage` is either missing, `undefined`, or does not have the expected methods from `decap-cms-lib-auth`.
fixEnsure you correctly import and initialize `authenticator` from `decap-cms-lib-auth` and pass it as a prop: `<AuthPage authenticator={authenticatorInstance} />`. 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.
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).
fixVerify 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.
AuthPage is not a function/component (or similar 'is not a constructor' error with CommonJS)
Incorrect import syntax, often trying to use CommonJS `require()` with an ESM-only package or using `import AuthPage from '...' ` for a named export.
fixEnsure 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. Audit
Dependencies
@emotion/reactrequiredStyling solution for React components
@emotion/styledrequiredStyling solution for React components
decap-cms-lib-authrequiredProvides core authentication logic and authenticator instances consumed by the UI components
decap-cms-ui-defaultrequiredProvides default UI components and styling conventions
lodashrequiredUtility belt library, commonly used across Decap CMS packages
prop-typesrequiredRuntime type checking for React props
reactrequiredCore library for building user interfaces