Amplify CLI JavaScript Frontend Plugin

Common errors

• No Amplify configuration found. Please configure Amplify in your app.

  cause The `aws-exports.js` file was not imported, or `Amplify.configure()` was not called with the configuration object.
  fix Ensure `import config from './aws-exports'; Amplify.configure(config);` is present and correctly located in your application's entry point.

• AuthError: Current user is not authenticated

  cause An operation requiring an authenticated user (e.g., accessing protected API routes, storage) was attempted without a valid user session.
  fix Implement proper authentication flows (signup, signin, session checks) using `Amplify.Auth` methods before attempting protected operations. Check user login state with `Amplify.Auth.currentAuthenticatedUser()` or similar methods.

• Type 'Observable<object>' is not assignable to type 'any'

  cause Often seen in TypeScript projects when using older versions of Amplify's API category or when observables are not correctly handled, specifically with GraphQL subscriptions.
  fix Ensure you are using `aws-amplify` v5 or higher and have `@aws-amplify/api` installed if using subscriptions. Explicitly type the observables or cast them where appropriate, or use `async/await` for GraphQL queries/mutations.

• Error: Command 'amplify add frontend' is not a valid amplify command.

  cause The installed `amplify-cli` version is too old or the plugin for handling 'frontend' commands is missing/corrupted.
  fix Update the Amplify CLI to the latest version globally (`npm update -g @aws-amplify/cli`) and ensure all related frontend plugins are correctly installed/updated.

Warnings

• gotcha The package `amplify-frontend-javascript` is a CLI plugin and not meant for direct import into your application code. Application code should import from the `aws-amplify` client library.
  Fix: Ensure you are installing `aws-amplify` (e.g., `npm install aws-amplify`) for client-side usage, and `amplify-cli` (e.g., `npm install -g @aws-amplify/cli`) for backend provisioning.
• breaking Amplify CLI and client library versions (e.g., `aws-amplify@5` to `aws-amplify@6`) can introduce breaking changes, especially in authentication workflows, API client generation, and UI components. Always consult the migration guide for major version upgrades.
  Fix: Before upgrading `aws-amplify` or the `amplify-cli`, review the official AWS Amplify documentation for release notes and migration guides specific to your current and target versions.
• gotcha The `aws-exports.js` configuration file generated by the CLI must be correctly imported and passed to `Amplify.configure()`. Changes to your Amplify backend (e.g., adding a new API or Auth category) require running `amplify push` and often regenerating `aws-exports.js`.
  Fix: After any `amplify push` operation, verify `aws-exports.js` is up-to-date and ensure your application code is importing the correct path for `aws-exports.js`.
• gotcha Module resolution issues (CommonJS vs. ESM) can arise in some JavaScript bundler configurations, especially in projects migrating to pure ESM or using older build tools. `aws-amplify` aims for universal compatibility but might require specific bundler configurations.
  Fix: Ensure your `tsconfig.json` (for TypeScript) and bundler configuration (Webpack, Rollup, Vite) are set up for proper ESM resolution, potentially requiring `moduleResolution: 'bundler'` or specific `plugins` for ESM/CJS interop.
• breaking Recent Amplify CLI versions (v14.x onwards) are migrating categories to AWS SDK v3. While `amplify-frontend-javascript` itself might not be directly affected, custom resources or functions that interact with AWS SDKs might experience breaking changes if not updated.
  Fix: For custom AWS Lambda functions or other custom resources managed by Amplify, ensure that any AWS SDK usage is compatible with v3. Review function code for deprecated SDK v2 calls and update to v3 if necessary.

Install

• npm install amplify-frontend-javascript npm
• yarn add amplify-frontend-javascript yarn
• pnpm add amplify-frontend-javascript pnpm

Imports

• Amplify
  wrong:

  const Amplify = require('aws-amplify');

  correct:

  import { Amplify } from 'aws-amplify';

  This package (`amplify-frontend-javascript`) is a CLI plugin and not directly imported by application code. These imports are for the `aws-amplify` client library, which frontend projects configure using the CLI plugin's output (e.g., `aws-exports.js`). For ESM, use `import`, for CJS, `require` is common but less preferred in modern frontend development.
• Auth
  wrong:

  import Auth from 'aws-amplify/lib/Auth';

  correct:

  import { Auth } from 'aws-amplify';

  Named export `Auth` for authentication features. Direct path imports like `aws-amplify/lib/Auth` are generally deprecated in favor of top-level named exports for better tree-shaking and stability across versions.
• API
  wrong:

  import { API } from '@aws-amplify/api';

  correct:

  import { API } from 'aws-amplify';

  Named export `API` for GraphQL and REST API interactions. While some categories have dedicated packages (e.g., `@aws-amplify/api`), the common practice for application code is to import from the main `aws-amplify` package.

Quickstart

This code demonstrates basic Amplify client-side configuration using `aws-exports.js` and examples for user authentication and GraphQL API interaction, which are common uses for Amplify in a JavaScript/TypeScript frontend.

import { Amplify } from 'aws-amplify';
import config from './aws-exports';

Amplify.configure(config);

// Example: Authenticate a user
async function signUp() {
  try {
    const { user } = await Amplify.Auth.signUp({
      username: 'testuser',
      password: 'password123',
      attributes: {
        email: 'test@example.com' // optional
      }
    });
    console.log('User signed up successfully:', user);
  } catch (error) {
    console.error('Error signing up:', error);
  }
}

// Example: Fetch data from a GraphQL API
async function fetchData() {
  try {
    const apiData = await Amplify.API.graphql({
      query: `
        query ListTodos {
          listTodos {
            items {
              id
              name
              description
            }
          }
        }
      `
    });
    console.log('API Data:', apiData);
  } catch (error) {
    console.error('Error fetching data:', error);
  }
}

signUp(); // Or fetchData();