Functions And API

Define a function in amplify/functions/<name>/resource.ts:

Create the handler at amplify/functions/<name>/handler.ts:

Import into amplify/backend.ts:

Sharing Code Between Functions

Each Lambda function is bundled independently from its own directory. Importing from a shared directory (amplify/shared/utils.ts) fails at build time.

Options:

1. Duplicate the shared code in each function directory
2. Symlink: ln -s ../../shared/utils.ts amplify/functions/my-fn/utils.ts
3. Package: Create a local npm package and install it in each function’s package.json

Handler Return Types

Common mistake: Writing an S3 handler like an API handler. S3Handler returns void, not a response object.

Environment Variables & Secrets

You SHOULD import environment variables from $amplify/env/<function-name> — this provides type-safe access to values defined in defineFunction. Values are also available at runtime via process.env.VAR_NAME, but the $amplify/env import is preferred because it gives you compile-time type checking and autocompletion.

For sensitive values, use secret():

Set secrets via CLI: echo -n "<value>" | npx ampx sandbox secret set MY_API_KEY.

Important: Use echo -n (no trailing newline) when piping values to secret set.

Important: The ampx sandbox secret set command is for local/sandbox development only. For apps deployed to Amplify Hosting, secrets must be created via the Amplify console (NOT ampx sandbox secret — that’s local only) — sandbox secrets are NOT available in hosted environments. See: https://docs.amplify.aws/react/deploy-and-host/fullstack-branching/secrets-and-vars/#set-secrets (opens in a new tab)

Environment Variables in Lambda

Recommended (type-safe):

Fallback (if $amplify/env causes esbuild bundling errors):

Scheduled Functions

Use schedule to invoke a function on a cron or natural-language schedule:

The handler must use EventBridgeHandler type:

Resource Access

Grant a function access to other Amplify resources:

For data schema access, use allow.resource() in authorization rules:

Lambda + API Gateway + Data Access

When a Lambda both accesses data tables AND is exposed via API Gateway, use resourceGroupName to avoid circular dependencies:

Custom Queries and Mutations

Use a.query() and a.mutation() with .handler() to add custom server-side logic through AppSync (no API Gateway needed):

How .handler() works: .handler() grants AppSync the permission to invoke the Lambda (AppSync→Lambda). The Lambda IS the resolver — it receives the GraphQL event directly. If the Lambda also needs to call the Data API or access DynamoDB tables for side effects, add allow.resource(fn) to the model with resourceGroupName: 'data' on the function to avoid circular dependencies.

typescriptCopy

// ❌ CIRCULAR DEPENDENCY — manual table grant in backend.ts
backend.data.resources.tables["Model"].grantReadData(backend.myFn.resources.lambda);

// ✅ Use resourceGroupName to co-locate the function in the data stack
const myFn = defineFunction({ name: 'my-fn', resourceGroupName: 'data' });
// Then in the schema: allow.resource(myFn) on the model

Gap: The Lambda resolver receives the GraphQL event but does NOT automatically get TABLE_NAME as an environment variable. Your Lambda must either:

1. Use the Amplify data client (generateClient()) which discovers tables automatically
2. Explicitly set env vars: myFunction.addEnvironment('TABLE_NAME', backend.data.resources.tables['Todo'].tableName)

When to use which:

• a.query() / a.mutation() with .handler() — AppSync-native, type-safe, uses the data schema. Preferred for most custom logic.
• API Gateway + Lambda — Use when you need REST endpoints, webhooks, or third-party integrations that require a specific URL.

REST API (API Gateway)

Create a REST API using CDK in amplify/backend.ts:

The handler must use APIGatewayProxyHandler type for REST API (v1):

HTTP API (API Gateway v2)

For a lightweight HTTP API:

The handler must use APIGatewayProxyHandlerV2 type for HTTP API (v2).

Backend Outputs

Use backend.addOutput() to expose custom values to the frontend via amplify_outputs.json:

Frontend reads custom outputs from the configured Amplify outputs.

Calling from Client

For custom queries and mutations defined via a.query() or a.mutation(), call them from the client:

For REST/HTTP API outputs added via backend.addOutput(), read the endpoint URL from amplify_outputs.json and use standard HTTP clients.

Pitfalls

• runtime must be an integer: Use runtime: 22, NOT runtime: "nodejs22.x". String format causes build errors.

• Wrong handler type: REST API (v1) requires APIGatewayProxyHandler with event.httpMethod; HTTP API (v2) requires APIGatewayProxyHandlerV2 with event.requestContext.http.method. Mixing them causes malformed responses. Both return { statusCode, body }.

• Missing resource access: A function without explicit grants cannot access auth, data, or storage resources — add grants in backend.ts.

• Secrets in plain environment: Sensitive values must use secret(), not string literals.

• createStack name collision: Stack names passed to backend.createStack() must be unique across the backend. Duplicate names cause deployment failures.

• Missing @types/node: Lambda functions require @types/node in devDependencies. Without it, process.env and Node.js globals cause TypeScript errors. Install: npm install --save-dev @types/node

• @types/aws-lambda: Lambda handlers (S3Handler, PreSignUpTriggerHandler, etc.) need this package for TypeScript types. Install at project root or in the function’s directory if it has its own package.json.

• AppSync identity typing: event.identity in custom handlers has varying types depending on auth mode. Use type assertion:

  typescriptCopy

  const identity = event.identity as { username?: string; sub?: string };
  const userId = identity?.username || identity?.sub || 'unknown';

• dataSource: 'NONE': Using a.handler.custom({ dataSource: 'NONE' }) causes “Data source not found” during deployment. Use a Lambda handler instead, or create the NONE data source explicitly via CDK.

• Lambda error types lost: Custom error classes thrown in Lambda arrive at the frontend as generic Error with only the message preserved. Error name, stack, and custom properties are stripped by AppSync. Return structured error data in the response instead.

Links

• Functions Overview (opens in a new tab)
• Set Up Function (opens in a new tab)
• Environment Variables and Secrets (opens in a new tab)
• Grant Access to Other Resources (opens in a new tab)
• Add custom queries and mutations (opens in a new tab)
• Connect to Existing Data Sources (opens in a new tab)