• Documentation
  • Pricing
© 2026 Serverless, Inc. All rights reserved.

Framework

  • Overview
  • Documentation
  • Plugins360
  • Pricing

Learn

  • Blog
  • GuidesUpdated
  • Examples240
  • Courses

Resources

  • Support
  • Security
  • Trust Center
  • Status

Community

  • Slack
  • GitHub47k
  • Forum
  • Meetups

Company

  • About
  • Careers
  • Contact
  • Partners

Legal

  • Terms of Service
  • Privacy Policy
  • Trademark
  • DMCA
Serverless Framework Logo

Serverless Framework

Intro
SetupUpgrading To V4ConceptsTutorialAWS CredentialsLicense Keys
DeployingPackagingBuildingTestingDev ModeServicesFunctions
OverviewHTTP (API Gateway v2)REST (API Gateway v1)ActiveMQApplication Load BalancerAlexa SkillAlexa Smart HomeCloudWatch EventCloudWatch LogCloudFrontCognito User PoolEventBridge EventIoTIoT Fleet ProvisioningKafkaKinesis & DynamoDBMSKRabbitMQS3ScheduleSNSSQSWebsocket
LayersManaged InstancesWeb Apps (Lambda Web Functions)Sandboxes (Lambda MicroVMs)MCP ServersAlertsVersion PruningDomainsIAM Function PermissionsParameters
OverviewSelf-reference serverless.ymlServerless CoreEnvironment VariablesCLI OptionsExternal YAML/JSON FilesJavascript propertiesGitDoppler
OverviewS3 ObjectsSSM Parameter Store & Secrets ManagerCloudFormation Stack Outputs
OverviewVaultTerraform State Output
ResourcesComposing ServicesDeployment BucketStateAgent SkillsPython support
OverviewRuntimeGatewayMemoryBrowserCode InterpreterDev Mode
API Gateway Proxy
OverviewGeneral ConfigurationAuthenticationAPI KeysData SourcesResolversPipeline FunctionsSubstitutionsCachingDelta SyncCustom DomainWAFCLI Commands
Deploying SAM/CFN TemplatesWorkflow Tips
OverviewCreating PluginsCLI OutputCustom CommandsCustom VariablesExtending the Configuration schemaExtending and overriding configuration
OverviewDashboardAxiom
Overviewagent docsagent inspectagent setupagent skills installagent skills list / readdeploydeploy functiondeploy listdevdiffinfoinvokeinvoke localloginlogin awslogin aws ssologsmetricspackageplugin installplugin uninstallprintprunereconcileremoverollbackrollback functionusage
OverviewConcepts
OverviewMetricsTracesTroubleshoot
OverviewNode.jsPython
OutputsProviders
OverviewBranch DeploymentsPreview DeploymentsCustom ScriptsTestingPrivate PackagesNotificationsMono ReposDeploy in your own CI/CDBest PracticesTroubleshootingFAQ
OverviewSetupToolsAWS Integration
Serverless.yml Reference
Examples and TutorialsConfiguration Validation
  1. Usage
  2. App Sync
  3. Resolvers

AppSync resolvers

The appSync.resolvers map attaches a resolver to each GraphQL field that needs one: the code that turns the field's arguments into a request to a data source and the response into the field's value. A UNIT resolver calls one data source; a PIPELINE resolver, the default kind, runs a list of pipeline functions in sequence. Resolver code is JavaScript for the APPSYNC_JS runtime, VTL mapping templates, or nothing at all for a direct Lambda resolver.

This unit resolver resolves Query.getPost with a JavaScript file and a DynamoDB data source:

appSync:
  name: blog-api
  dataSources:
    postsTable:
      type: AMAZON_DYNAMODB
      config:
        tableName: !Ref PostsTable
  resolvers:
    Query.getPost:
      kind: UNIT
      dataSource: postsTable
      code: resolvers/getPost.js

The code path is relative to the service directory. resolvers/getPost.js exports a request and a response function:

import { util } from '@aws-appsync/utils'

export function request(ctx) {
  return {
    operation: 'GetItem',
    key: util.dynamodb.toMapValues({ id: ctx.args.id }),
  }
}

export function response(ctx) {
  return ctx.result
}

Without kind: UNIT, a resolver is a pipeline resolver and requires functions instead of dataSource.

Resolver keys

Each key of appSync.resolvers is either Type.field (Query.getPost), or any name with the type and field set as type and field:

appSync:
  name: blog-api
  resolvers:
    getPostResolver:
      type: Query
      field: getPost
      kind: UNIT
      dataSource: postsTable
      code: resolvers/getPost.js

Each resolver accepts these keys:

KeyTypeDefaultDescription
typestringFrom the Type.field keyThe GraphQL type. Required when the key isn't Type.field.
fieldstringFrom the Type.field keyThe GraphQL field. Required when the key isn't Type.field.
kindUNIT or PIPELINEPIPELINEThe resolver kind.
dataSourcestring or objectRequired for UNITThe name of a data source in appSync.dataSources, or an inline data source.
functionslistRequired for PIPELINEThe pipeline functions to run in order: names, or inline definitions.
codestringSee Resolver runtimesPath to a JavaScript or TypeScript file, relative to the service directory.
requeststringNonePath to a VTL request mapping template, relative to the service directory.
responsestringNonePath to a VTL response mapping template, relative to the service directory.
maxBatchSizenumber, 1–2000NoneFor UNIT resolvers with a Lambda data source: the maximum number of requests AppSync sends to the function in one batch invocation.
cachingboolean or objectNoneSee Resolver caching.
syncobjectNoneConflict detection and resolution. See Delta Sync.
substitutionsmapNoneSee AppSync substitutions.

Resolver runtimes

The keys a resolver sets decide its runtime:

Keys setRuntime
codeJavaScript (APPSYNC_JS 1.0.0).
request and/or response, without codeVTL mapping templates.
None of them, kind: UNITA direct Lambda resolver. Use it only with a Lambda data source.
None of them, kind: PIPELINEJavaScript with a default request and response that pass the last function's result through.

JavaScript resolvers

A JavaScript resolver's code file exports request(ctx), which returns the request for the data source, and response(ctx), which returns the field's value. The Framework bundles the file with esbuild before deploying, so it can import other files and npm packages; see Resolver bundling.

VTL resolvers

A VTL resolver sets request and response to mapping template files:

appSync:
  name: blog-api
  resolvers:
    Query.getPost:
      kind: UNIT
      dataSource: postsTable
      request: mapping-templates/getPost.request.vtl
      response: mapping-templates/getPost.response.vtl

The request template in mapping-templates/getPost.request.vtl:

{
  "version": "2018-05-29",
  "operation": "GetItem",
  "key": {
    "id": $util.dynamodb.toDynamoDBJson($ctx.args.id)
  }
}

The response template in mapping-templates/getPost.response.vtl:

$util.toJson($ctx.result)

Direct Lambda resolvers

A direct Lambda resolver has kind: UNIT, a Lambda data source and no code, request or response. AppSync sends the function the full context (arguments, identity, source, info and more) and uses the function's return value as the field's value:

provider:
  name: aws
  runtime: nodejs24.x

appSync:
  name: blog-api
  dataSources:
    postsFunction:
      type: AWS_LAMBDA
      config:
        function:
          handler: functions/posts.handler
  resolvers:
    Query.getPost:
      kind: UNIT
      dataSource: postsFunction

The handler in functions/posts.mjs:

export const handler = async (event) => {
  const { id } = event.arguments
  return { id, title: `Post ${id}` }
}

Pipeline resolvers

A pipeline resolver runs its functions in order. Each function's code file exports request and response, like a unit resolver's, and can read the previous function's result from ctx.prev.result. The resolver's own code (or request and response templates) runs before the first function and after the last:

appSync:
  name: blog-api
  pipelineFunctions:
    authorizePost:
      dataSource: postsTable
      code: functions/authorizePost.js
    getPost:
      dataSource: postsTable
      code: functions/getPost.js
  resolvers:
    Query.getPost:
      functions:
        - authorizePost
        - getPost

Without code, request or response, the Framework gives a pipeline resolver this JavaScript code, which passes the last function's result through:

export function request() {
  return {}
}

export function response(ctx) {
  return ctx.prev.result
}

Resolver bundling

AppSync accepts one JavaScript file per resolver or function. The Framework bundles each code file with esbuild, using the file as the entry point, so the code can import local modules and npm packages. @aws-appsync/utils stays external because the APPSYNC_JS runtime provides it. This resolver imports helpers from another file:

import { util } from '@aws-appsync/utils'
import { buildUpdate } from '../lib/helpers.js'

export function request(ctx) {
  const { id, ...values } = ctx.args.input
  return {
    operation: 'UpdateItem',
    key: util.dynamodb.toMapValues({ id }),
    update: buildUpdate(values),
    condition: {
      expression: 'attribute_exists(#id)',
      expressionNames: { '#id': 'id' },
    },
  }
}

export function response(ctx) {
  return ctx.result
}

Imported code must also run in the APPSYNC_JS runtime, which supports a subset of JavaScript. To change the esbuild options, or to send files unbundled, see esbuild options for JavaScript resolvers.

TypeScript resolvers

A code path ending in .ts is transpiled to JavaScript while bundling, with no extra configuration:

appSync:
  name: blog-api
  resolvers:
    Query.getPost:
      kind: UNIT
      dataSource: postsTable
      code: resolvers/getPost.ts

The resolver in resolvers/getPost.ts can use the types from @aws-appsync/utils (install it as a dev dependency for the types):

import { Context, util } from '@aws-appsync/utils'

export function request(ctx: Context) {
  return {
    operation: 'GetItem',
    key: util.dynamodb.toMapValues({ id: ctx.args.id }),
  }
}

export function response(ctx: Context) {
  return ctx.result
}

esbuild removes the types without checking them; run tsc --noEmit to type-check.

Inline data sources

A UNIT resolver's dataSource can be a full data source definition instead of a name, for a data source that only this resolver uses. With a Lambda data source, the function can be defined inline too:

provider:
  name: aws
  runtime: nodejs24.x

appSync:
  name: blog-api
  resolvers:
    Query.getPost:
      kind: UNIT
      dataSource:
        type: AWS_LAMBDA
        config:
          function:
            handler: functions/getPost.handler

The Framework names an inline data source after the resolver key, with its first character that isn't a letter or _ replaced by _: Query.getPost becomes the data source and function name Query_getPost.

Inline pipeline functions

A pipeline resolver's functions list can hold full pipeline function definitions instead of names, for functions that only this resolver uses:

appSync:
  name: blog-api
  resolvers:
    Query.getPost:
      functions:
        - dataSource: postsTable
          code: functions/getPost.js

The Framework names inline functions after the resolver key and their position in the list: Query_getPost_0, Query_getPost_1.

Resolver caching

The caching key of a resolver caches its results in the API's server-side cache, which appSync.caching creates. With behavior: PER_RESOLVER_CACHING, AppSync caches only the resolvers that set caching:

appSync:
  name: blog-api
  caching:
    behavior: PER_RESOLVER_CACHING
    type: SMALL
  resolvers:
    Query.getPost:
      kind: UNIT
      dataSource: postsTable
      code: resolvers/getPost.js
      caching:
        ttl: 60
        keys:
          - '$context.arguments.id'
KeyTypeDefaultDescription
ttlinteger, 1–3600appSync.caching.ttl, else 3600Seconds to keep a cached result.
keyslist of strings$context.arguments, $context.source and $context.identity (AppSync default)The values that make up the cache key: entries from those three maps, such as $context.arguments.id.

The $context.arguments.id key shares each cached post among all callers, which suits data that every caller may read. For a resolver whose result depends on the caller, such as one that checks ownership, add an identity field such as $context.identity.sub to keys, or omit keys to use AppSync's default keys, which include $context.identity.

caching: true caches the resolver with the API-wide TTL and AppSync's default caching keys, as when keys is omitted.

Set appSync.caching.type: without it, the Framework creates a legacy T2_SMALL cache instance. The instance types and hourly billing are in AppSync caching.

Split resolvers across files

appSync.resolvers also accepts a list of maps, which the Framework merges into one. Combined with the ${file()} variable, each file holds some of the resolvers:

appSync:
  name: blog-api
  resolvers:
    - ${file(appsync/resolvers/users.yml)}
    - ${file(appsync/resolvers/posts.yml)}

Each file is a map of resolver keys to definitions, without the appSync and resolvers parent keys.

Related pages

  • AppSync pipeline functions
  • AppSync data sources
  • AWS AppSync JavaScript resolver reference
  • AWS AppSync VTL resolver reference
Edit this page
Prev Data SourcesNextPipeline Functions

Contents

  • AppSync resolvers
  • Resolver keys
  • Resolver runtimes
  • JavaScript resolvers
  • VTL resolvers
  • Direct Lambda resolvers
  • Pipeline resolvers
  • Resolver bundling
  • TypeScript resolvers
  • Inline data sources
  • Inline pipeline functions
  • Resolver caching
  • Split resolvers across files
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport