Amplify CLI Function Plugin

4.3.2 verified Sat Apr 25 auth: no javascript

The @aws-amplify/amplify-category-function package is an official Amplify CLI plugin for managing AWS Lambda functions within an Amplify project. It provides commands to add, build, push, and remove function resources, leveraging AWS CloudFormation for infrastructure as code. The current stable version is 5.8.0 (part of Amplify CLI v14.3.0). It requires the Amplify CLI environment and is typically used via the `amplify` command-line interface. Key differentiators: tight integration with Amplify's backend management, automatic IAM role generation, and support for multiple runtimes. Compared to raw AWS SDK usage, it abstracts away CloudFormation templates and provides a guided CLI workflow.

Common errors

error Cannot find module '@aws-amplify/amplify-category-function' ↓

cause Package not installed or not in `node_modules`.

fix

Run npm install @aws-amplify/amplify-category-function or ensure it's added to your Amplify project.

error add is not a function ↓

cause Using CommonJS `require` with ESM-only package.

fix

Change to import { add } from '@aws-amplify/amplify-category-function'.

error The function 'myFunction' already exists in the project. ↓

cause Attempting to add a function with a name that already exists in `amplify/backend/function/`.

fix

Use a different name, or remove the existing function first with remove.

error Cannot read property 'handler' of undefined ↓

cause The function source directory is missing a valid handler file.

fix

Ensure the specified path contains a handler file (e.g., index.js) with the correct export.

Warnings

breaking ESM-only from version 5.0 onwards; CommonJS require() will fail. ↓

fix Use ES module imports: `import { add } from '@aws-amplify/amplify-category-function'`.

deprecated The `amplify function add` command with interactive prompts may be deprecated in future versions; prefer programmatic API. ↓

fix Use the `add` function with options object instead of relying on CLI prompts.

gotcha The function resource name must match an existing directory in `amplify/backend/function/`; otherwise, `add` will fail. ↓

fix Ensure the directory exists before calling `add`, or use the interactive CLI which creates it.

breaking In version 5.8.0, the MaxResults parameter for function listing was reduced from 50 to 10, which may affect scripts that iterate over functions. ↓

fix Update code to handle pagination with smaller page size.

gotcha The `build` command only builds Node.js functions; other runtimes (Python, Go) require manual build steps. ↓

fix For non-Node.js runtimes, use external build tools and ensure the output is placed in the source directory.

Install

npm install amplify-category-function

yarn add amplify-category-function

pnpm add amplify-category-function

Imports

add

wrong

const add = require('@aws-amplify/amplify-category-function').add

correct

import { add } from '@aws-amplify/amplify-category-function'

ESM-only since version 5.0; CommonJS require is deprecated

build

wrong

import { buildFunction } from '@aws-amplify/amplify-category-function'

correct

import { build } from '@aws-amplify/amplify-category-function'

Function name is 'build', not 'buildFunction'

push

wrong

import { pushResources } from '@aws-amplify/amplify-category-function'

correct

import { push } from '@aws-amplify/amplify-category-function'

Use 'push' for pushing function resources

remove

wrong

import { removeFunction } from '@aws-amplify/amplify-category-function'

correct

import { remove } from '@aws-amplify/amplify-category-function'

The exported symbol is 'remove'

Quickstart

Demonstrates how to add, build, push, and remove an AWS Lambda function using the plugin's ESM imports. Assumes an existing Amplify project.

// Ensure you have an initialized Amplify project
import { add, build, push } from '@aws-amplify/amplify-category-function';

// Add a new function (interactive or with options)
await add({
  name: 'myFunction',
  runtime: 'nodejs18.x',
  handler: 'index.handler',
  path: './amplify/backend/function/myFunction/src',
  // optional: override default settings
});

// Build the function
await build();

// Push to cloud
await push();

// Remove
import { remove } from '@aws-amplify/amplify-category-function';
await remove({ name: 'myFunction' });