Amazon Cognito Auth JS Promises

1.1.5 verified Sat Apr 25 auth: no javascript deprecated

Wrapper around amazon-cognito-auth-js providing Promise-based APIs for Cognito User Pools authentication in browser apps. Version 1.1.5 (last release Feb 2020) is stable but unmaintained. It supports sign-up, sign-in, sign-out, and token management via OAuth2 flows. Compared to the newer @aws-amplify/auth or amazon-cognito-identity-js, this package offers a lighter, promise-based interface but lacks ongoing updates and TypeScript types. Requires a User Pool App Client ID, App Web Domain, and scope array configured in AWS Console.

Common errors

error Cannot find module 'amazon-cognito-auth-js' ↓

cause Missing peer dependency amazon-cognito-auth-js.

fix

npm install amazon-cognito-auth-js

error TypeError: auth.getSession is not a function ↓

cause Using CommonJS require without accessing .CognitoAuth property.

fix

const { CognitoAuth } = require('amazon-cognito-auth-js-promises'); then const auth = new CognitoAuth(...);

Warnings

deprecated Package is not actively maintained; no updates since February 2020. Consider migrating to @aws-amplify/auth or amazon-cognito-identity-js. ↓

fix Replace with @aws-amplify/auth: npm install @aws-amplify/auth

gotcha Token scopes must include 'openid' for ID token to be returned. Missing 'openid' may cause silent failures. ↓

fix Add 'openid' to TokenScopesArray.

breaking In v1.1.0, the promise methods were renamed (e.g., getSession vs getSessionAsync) – check the changelog if upgrading from earlier versions. ↓

fix Use the promise-based method names as documented; avoid the old 'Async' suffix.

Install

npm install amazon-cognito-auth-js-promises

yarn add amazon-cognito-auth-js-promises

pnpm add amazon-cognito-auth-js-promises

Imports

CognitoAuth

wrong

const CognitoAuth = require('amazon-cognito-auth-js-promises').CognitoAuth

correct

import { CognitoAuth } from 'amazon-cognito-auth-js-promises'

ES module import is preferred; CommonJS require works but must access .CognitoAuth.

CognitoAuth

wrong

const CognitoAuth = require('amazon-cognito-auth-js-promises')

correct

const { CognitoAuth } = require('amazon-cognito-auth-js-promises')

Direct require returns the module object, not CognitoAuth class.

default

wrong

import { default } from 'amazon-cognito-auth-js-promises'

correct

import AmazonCognitoIdentity from 'amazon-cognito-auth-js-promises'

Default import is an object containing all exports; not recommended.

Quickstart

Creates a CognitoAuth instance with environment variables and initiates a login session using promises.

import { CognitoAuth } from 'amazon-cognito-auth-js-promises';

const auth = new CognitoAuth({
  ClientId: process.env.COGNITO_CLIENT_ID ?? '',
  AppWebDomain: process.env.COGNITO_DOMAIN ?? '',
  TokenScopesArray: ['openid', 'email', 'profile'],
  RedirectUriSignIn: process.env.COGNITO_REDIRECT_SIGN_IN ?? '',
  RedirectUriSignOut: process.env.COGNITO_REDIRECT_SIGN_OUT ?? '',
  IdentityProvider: '',
  UserPoolId: process.env.COGNITO_USER_POOL_ID ?? '',
  AdvancedSecurityDataCollectionFlag: true,
});

auth.getSession()
  .then(session => console.log(session))
  .catch(err => console.error(err));