• 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. General Configuration

AppSync API configuration

The top-level appSync block in serverless.yml holds one AppSync GraphQL API per service. This page covers the keys that apply to the whole API: its name, schema files, logging, tracing, visibility, query limits, environment variables, tags and the esbuild options for JavaScript resolvers. Data sources, resolvers, authentication and the other features have their own pages, linked from the AppSync overview.

The following appSync block sets the API-wide keys alongside the required name and authentication:

appSync:
  name: blog-api
  schema: schema.graphql
  authentication:
    type: API_KEY
  xrayEnabled: true
  introspection: false
  queryDepthLimit: 10
  resolverCountLimit: 500
  logging:
    level: ERROR
    retentionInDays: 14
  environment:
    POSTS_TABLE: !Ref PostsTable
  tags:
    team: blog

AppSync API-wide keys

All keys sit directly under appSync. Keys not listed on this page or the linked pages are rejected with invalid (unknown) property.

KeyTypeDefaultDescription
namestringRequiredThe name of the AppSync API.
authenticationobjectRequiredThe default authorization mode. See AppSync authentication.
schemastring or list of stringsschema.graphqlSchema file paths or glob patterns, relative to the service directory. See GraphQL schema files.
xrayEnabledbooleanfalseEnables AWS X-Ray tracing for the API.
visibilityGLOBAL or PRIVATEGLOBAL (AppSync default)PRIVATE makes the API reachable only from a VPC endpoint. AppSync sets visibility when it creates the API, so changing this value on a deployed API replaces the API, with a new API ID and new endpoint URLs.
introspectionbooleantrueSet to false to reject GraphQL introspection queries.
queryDepthLimitinteger, 1–75No limitThe maximum number of nested levels in a query.
resolverCountLimitinteger, 1–1000AppSync default (10000)The maximum number of resolvers one request can invoke.
environmentmap of stringsNoneEnvironment variables for resolvers and functions. See AppSync environment variables.
tagsmap of stringsNoneTags for the API. The same tags apply to the WAF web ACL the Framework creates.
loggingobjectNo loggingField-level logging to CloudWatch Logs. See AppSync logging.
esbuildobject or falseesbuild with the defaults belowOptions for bundling JavaScript and TypeScript resolvers. See esbuild options for JavaScript resolvers.
additionalAuthenticationslistNoneAdditional authorization modes. See AppSync authentication.
apiKeyslistNoneSee AppSync API keys.
dataSourcesmap, or list of mapsNoneSee AppSync data sources.
resolversmap, or list of mapsNoneSee AppSync resolvers.
pipelineFunctionsmap, or list of mapsNoneSee AppSync pipeline functions.
substitutionsmapNoneSee AppSync substitutions.
cachingobjectNo cacheSee AppSync caching.
domainobjectNoneSee AppSync custom domain.
wafobjectNoneSee AppSync WAF.

The Framework checks the appSync block against its schema before packaging. With the default configValidationMode: warn, an invalid block prints Invalid AppSync Configuration followed by each problem as a warning and the command continues; with configValidationMode: error, the command stops; with off, nothing is printed.

GraphQL schema files

The appSync.schema key names the GraphQL schema file, relative to the service directory (the directory that holds serverless.yml). Without it, the Framework reads schema.graphql:

appSync:
  name: blog-api
  schema: api/schema.graphql

To split the schema across files, list them, or use glob patterns:

appSync:
  name: blog-api
  schema:
    - schemas/base.graphql
    - schemas/users/*.graphql

Before deploying, the Framework validates the schema, with the AppSync directives and scalars (such as @aws_iam, @aws_subscribe and AWSDateTime) predefined. To run the same check without deploying, use serverless appsync validate-schema.

Merging schema files

With several schema files, the Framework merges them into one schema before sending it to AppSync. Declare Query and Mutation once, then add fields to them with object extensions in the other files:

# schemas/base.graphql
type Query
type Mutation
# schemas/users.graphql
extend type Query {
  getUser(id: ID!): User
}

extend type Mutation {
  createUser(name: String!): User
}

type User {
  id: ID!
  name: String!
}

The merged schema that AppSync receives has a single Query type with getUser and a single Mutation type with createUser.

The merge keeps descriptions written with three double quotes (""") and & between implemented interfaces, drops # comments, and sorts the type definitions alphabetically. A schema from a single file is sent unchanged, so to keep # comments, put the whole schema in one file.

AppSync logging

The appSync.logging block sends AppSync field-level logs to CloudWatch Logs:

appSync:
  name: blog-api
  logging:
    level: ERROR
    retentionInDays: 14
KeyTypeDefaultDescription
levelNONE, ERROR, INFO, DEBUG or ALLRequiredThe field log level. INFO includes messages your resolvers write with console.log, DEBUG also includes console.debug messages, and ALL adds field-level tracing.
enabledbooleantrueSet to false to keep the block but turn logging off.
excludeVerboseContentbooleanfalseLeaves headers, context and evaluated mapping templates out of the logs, at any level.
retentionInDaysintegerprovider.logRetentionInDaysDays to keep the logs. When neither is set, the logs never expire.
roleArnstring or intrinsicA role the Framework createsThe IAM role AppSync assumes to write the logs.

With logging enabled, the Framework creates the log group /aws/appsync/apis/<api id> with the retention above. Without roleArn, it also creates an IAM role that AppSync assumes, allowed logs:CreateLogGroup, logs:CreateLogStream and logs:PutLogEvents on that log group only. With enabled: false, the Framework creates no log group, no role and no log configuration. serverless appsync logs prints the log group's events.

AppSync environment variables

The appSync.environment map sets AppSync environment variables, which JavaScript resolvers read from ctx.env and VTL templates from $ctx.env. Values are strings or CloudFormation intrinsic functions:

appSync:
  name: blog-api
  environment:
    POSTS_TABLE: !Ref PostsTable
    STAGE: ${sls:stage}

A JavaScript resolver then reads ctx.env.POSTS_TABLE. AppSync allows up to 50 variables per API; keys start with a letter, are at least two characters long and contain only letters, numbers and _; values are up to 512 characters and are always strings. For secrets, read them at run time from AWS Secrets Manager or Parameter Store instead.

esbuild options for JavaScript resolvers

The Framework bundles every JavaScript or TypeScript resolver and pipeline function code file with esbuild into one ESM file, as AppSync requires. The appSync.esbuild block passes extra options to esbuild:

appSync:
  name: blog-api
  esbuild:
    target: es2020
    sourcemap: false

Without the block, the Framework uses target: esnext, sourcemap: inline, sourcesContent: false and treeShaking: true. It always sets platform: node, format: esm, bundle: true, write: false, the entry point and external: ['@aws-appsync/utils'], and ignores those keys in appSync.esbuild. Some esbuild options produce code the APPSYNC_JS runtime rejects; see the AWS guidance on bundling, TypeScript and source maps.

To send each file to AppSync unchanged, set esbuild: false. Each code file must then be a single JavaScript ESM file whose only imports are @aws-appsync/* modules.

Related pages

  • AppSync overview
  • AppSync resolvers
  • AppSync CLI commands
  • Serverless.yml reference
Edit this page
Prev OverviewNextAuthentication

Contents

  • AppSync API configuration
  • AppSync API-wide keys
  • GraphQL schema files
  • Merging schema files
  • AppSync logging
  • AppSync environment variables
  • esbuild options for JavaScript resolvers
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport