Amplify CLI Core

4.0.4 verified Sat Apr 25 auth: no javascript

Core library for AWS Amplify CLI, providing shared utilities, configuration management, and API abstractions used by all Amplify CLI plugins. Current stable version is 4.0.4. Part of the Amplify CLI monorepo which releases roughly weekly. Key differentiators: provides centralized error handling, feature flags, and path management for the CLI ecosystem. Unlike @aws-amplify/cli which is the CLI entry point, this package is the internal toolkit for plugin authors and extension developers.

Common errors

error Cannot find module 'amplify-cli-core' ↓

cause The package is internal and not published to npm separately from the Amplify CLI monorepo.

fix

Install the entire Amplify CLI: npm install -g @aws-amplify/cli. The core package is bundled and not meant for direct external consumption.

error TypeError: stateManager.getBackendConfig is not a function ↓

cause stateManager was not properly initialized; typically occurs when called outside an Amplify CLI plugin context.

fix

Ensure you have an active Amplify project and are running within a plugin command that receives $TSContext. Do not import stateManager standalone.

error Property 'amplify' does not exist on type '$TSContext' ↓

cause Using a newer version of the CLI (v4+) with old typescript definitions from v3.

fix

Update amplify-cli-core to v4 and regenerate TypeScript types. Also update peer imports: context.amplify is now context.amplify (still valid) but its methods have changed.

Warnings

breaking The $TSContext type changed significantly between v3 and v4. The 'amplify' property now has a different shape. ↓

fix Update your plugin code to use new context properties: context.amplify.getCategoryPluginInfo vs context.pluginPlatform.

deprecated stateManager.getResourceStatus() deprecated in v4. Use stateManager.getCurrentResourceStatus() instead. ↓

fix Replace stateManager.getResourceStatus() with stateManager.getCurrentResourceStatus() — the new method returns a different object structure.

gotcha JSONUtilities.parse can throw on malformed JSON — always wrap in try/catch unless you're certain of input. ↓

fix Wrap JSONUtilities.parse calls in try/catch or use the safeParse option available in v4+.

Install

npm install amplify-cli-core

yarn add amplify-cli-core

pnpm add amplify-cli-core

Imports

$TSContext
wrong
```
import { $TSContext } from 'aws-amplify'
```
correct
```
import { $TSContext } from 'amplify-cli-core'
```
This is the main context type passed through all Amplify CLI plugin commands.

JSONUtilities

wrong

import { JSONUtilities } from 'amplify-cli'

correct

import { JSONUtilities } from 'amplify-cli-core'

Utility for JSON parsing/writing with Amplify-specific handling.

PathManager
```
import { PathManager } from 'amplify-cli-core'
```
Manages file paths for Amplify project structure. Commonly used for accessing backend-config, team-provider-info, etc.
stateManager
```
import { stateManager } from 'amplify-cli-core'
```
Singleton for reading and writing Amplify CLI state files (e.g., local-env-info.json, backend-config.json).

Quickstart

Demonstrates importing core types and utilities to read Amplify project's backend configuration.

import { $TSContext, stateManager, JSONUtilities, PathManager } from 'amplify-cli-core';

async function getBackendConfig(context: $TSContext) {
  const backendConfigPath = PathManager.getBackendConfigFilePath();
  const backendConfig = stateManager.getBackendConfig(undefined, {
    throwIfNotExist: false,
  });
  if (!backendConfig) {
    context.print.warning('No backend config found.');
    return null;
  }
  return JSONUtilities.parse(JSON.stringify(backendConfig)) as Record<string, any>;
}