Amplify CLI API Category Plugin

Common errors

• GraphQL schema validation failed

  cause The `schema.graphql` file contains syntax errors, invalid directives, or conflicts with Amplify's GraphQL Transformer rules.
  fix Review `amplify/backend/api/<api-name>/schema.graphql` for errors. Use an IDE with GraphQL syntax highlighting and refer to Amplify's GraphQL Transformer documentation for correct directive usage. Running `amplify api gql-compile` can help identify specific issues.

• An error occurred during the push operation: Your GraphQL Schema is using "@key" directive from an older version of the GraphQL Transformer.

  cause Your project is using an older GraphQL schema incompatible with the current Amplify CLI's GraphQL Transformer (e.g., attempting to use `@key` with Transformer v2).
  fix Migrate your GraphQL schema to Transformer v2 using `amplify migrate api`. Update `@key` directives to `@primaryKey` or `@index` as appropriate, and review `@auth` rules for the new 'deny-by-default' behavior.

• Stack named 'amplify-<projectname>-api-<envname>' already exists

  cause A CloudFormation stack for your API environment exists but is in an unrecoverable state, or a previous deployment failed, leaving residual resources.
  fix Check the AWS CloudFormation console for your Amplify project's stacks. If a stack is stuck in a `ROLLBACK_COMPLETE` or `UPDATE_ROLLBACK_FAILED` state, you may need to manually delete it. If you are confident, `amplify push --force` can sometimes resolve minor inconsistencies, but this should be used with caution.

• Error: There are no categories configured in the project. Use 'amplify add <category>' to add a category.

  cause The Amplify project has not been properly initialized or the `amplify init` command was not run from the project root.
  fix Ensure you are in the root directory of your Amplify project and run `amplify init` if this is a new project, or `amplify pull` if you are cloning an existing project. Then, use `amplify add api` to configure your API.

Warnings

• breaking Upgrading the Amplify CLI (especially across major versions) often introduces breaking changes, particularly concerning the GraphQL Transformer (e.g., v1 to v2 migration). Directives like `@key` were replaced by `@primaryKey` and `@index`, and authorization rules (`@auth`) shifted to a 'deny-by-default' approach requiring explicit configuration.
  Fix: Always consult the official Amplify CLI migration guides for your specific version. Utilize `amplify migrate api` for automated schema migration, and manually review and update `@auth`, `@key`, and relationship directives.
• gotcha Manual modifications to Amplify-provisioned API resources directly in the AWS console (e.g., AppSync resolvers, DynamoDB tables) can lead to CloudFormation drift. Subsequent `amplify push` operations might overwrite these manual changes or fail due to state inconsistencies.
  Fix: Manage all Amplify-generated API resources through the CLI. If manual changes are unavoidable, explore Amplify's 'Overrides' feature (CLI v7+) or consider defining custom resources to prevent drift.
• gotcha Frequent `amplify push` operations during active API development, especially with complex GraphQL schemas, can be slow. This can hinder rapid iteration due to the time required for CloudFormation deployments.
  Fix: Leverage `amplify mock api` for local development and testing of GraphQL APIs and resolvers, enabling faster feedback loops without cloud deployments. For significant schema changes, consider using feature branches and reviewing `amplify status` before pushing.
• deprecated The `amplify rebuild api` command, used in GraphQL Transformer v1, is deprecated and no longer reliably works with newer transformer versions.
  Fix: Instead of `amplify rebuild api`, use `amplify push` after schema changes. If encountering persistent issues, a common workaround is to back up your schema, `amplify remove api`, `amplify push`, then `amplify add api` with the backed-up schema, followed by another `amplify push`.

Install

• npm install amplify-category-api npm
• yarn add amplify-category-api yarn
• pnpm add amplify-category-api pnpm

Imports

• No direct programmatic imports for application code
  wrong:

  import { addApi } from '@aws-amplify/amplify-category-api';
  const apiCategory = require('@aws-amplify/amplify-category-api');

  correct:
  This package is an internal plugin for the AWS Amplify CLI and is not designed for direct programmatic import or usage in user applications. Developers interact with its functionality exclusively through the `amplify api` command-line interface. For programmatic access to Amplify APIs within your application, use `@aws-amplify/api` (v6+).

Quickstart

Demonstrates initializing an Amplify project, adding a GraphQL API using the CLI, and deploying it to the AWS cloud.

npx create-react-app my-amplify-app
cd my-amplify-app
amplify init # Follow prompts to initialize a new Amplify project

# Add a GraphQL API
amplify add api
  # Choose 'GraphQL'
  # Choose 'Authorize and configure with AWS IAM (recommended for multi-user apps)'
  # Choose 'Single object with fields (e.g., "Todo")' or 'Blank schema'
  # Edit schema.graphql if desired (e.g., add more @model types)

# Deploy the API to the cloud
amplify push # Confirm changes and deploy