• 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. Substitutions

AppSync substitutions

Substitutions replace placeholders in AppSync resolver and pipeline function code with values from serverless.yml when you deploy, such as a DynamoDB table name, an ARN, the stage or the Region. Substitutions are deprecated: use AppSync environment variables instead, which resolvers read from ctx.env at run time without rewriting the code.

This configuration defines a global substitution with the table name and uses it in a JavaScript resolver:

appSync:
  name: blog-api
  substitutions:
    postsTable: !Ref PostsTable
  resolvers:
    Query.getPosts:
      kind: UNIT
      dataSource: postsTable
      code: resolvers/getPosts.js

In JavaScript, a placeholder is the substitution's name between # characters, inside a string. resolvers/getPosts.js reads several posts by ID:

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

export function request(ctx) {
  return {
    operation: 'BatchGetItem',
    tables: {
      '#postsTable#': {
        keys: ctx.args.ids.map((id) => util.dynamodb.toMapValues({ id })),
      },
    },
  }
}

export function response(ctx) {
  if (ctx.error) {
    util.error(ctx.error.message, ctx.error.type)
  }
  return ctx.result.data['#postsTable#']
}

When DynamoDB processes only part of the batch, AppSync sets ctx.error and returns null for each unprocessed key; the response handler raises that error, so clients don't mistake an unread post for a missing one.

Where substitutions are defined

Substitutions are maps of names to values at three levels:

  • appSync.substitutions: available to every resolver and pipeline function.
  • appSync.resolvers.<resolver>.substitutions: available to that resolver only.
  • appSync.pipelineFunctions.<function>.substitutions: available to that pipeline function only.

When a resolver or pipeline function defines a name that is also global, its own value wins. Names contain letters, digits, _ and -. Values are strings or CloudFormation intrinsic functions such as !Ref and !GetAtt; CloudFormation resolves intrinsic values during the deploy.

Placeholder syntax

The placeholder syntax depends on the runtime of the file:

FilePlaceholderExample
JavaScript or TypeScript code#name#'#postsTable#'
VTL request or response template${name}"${postsTable}"

The Framework replaces only placeholders whose name is defined at one of the three levels; other text, including VTL references such as ${ctx.args.id}, stays unchanged. In JavaScript files, the replacement runs on the bundled code, after esbuild.

This VTL request template uses the same postsTable substitution:

#set($keys = [])
#foreach($id in $ctx.args.ids)
  $util.qr($keys.add({ "id": $util.dynamodb.toDynamoDB($id) }))
#end
{
  "version": "2018-05-29",
  "operation": "BatchGetItem",
  "tables": {
    "${postsTable}": {
      "keys": $util.toJson($keys)
    }
  }
}

Related pages

  • AppSync environment variables
  • AppSync resolvers
  • AppSync pipeline functions
Edit this page
Prev Pipeline FunctionsNextCaching

Contents

  • AppSync substitutions
  • Where substitutions are defined
  • Placeholder syntax
  • Related pages

Related

GuidesPluginsExamplesSlack CommunitySupport