AppSync

Reference doc for the `sst.aws.AppSync` component.

The AppSync component lets you add an Amazon AppSync GraphQL API to your app.

Create a GraphQL API

const api = new sst.aws.AppSync("MyApi", {
  schema: "schema.graphql",
});

Add a data source

const lambdaDS = api.addDataSource({
  name: "lambdaDS",
  lambda: "src/lambda.handler",
});

Add a resolver

api.addResolver("Query user", {
  dataSource: lambdaDS.name,
});

Constructor

new AppSync(name, args, opts?)

Parameters

name string
args AppSyncArgs
opts? ComponentResourceOptions

AppSyncArgs

domain?

Type Input<string | Object>

cert?
dns?
name

Set a custom domain for your AppSync GraphQL API.

Automatically manages domains hosted on AWS Route 53, Cloudflare, and Vercel. For other providers, you’ll need to pass in a cert that validates domain ownership and add the DNS records.

By default this assumes the domain is hosted on Route 53.

{
  domain: "example.com"
}

For domains hosted on Cloudflare.

{
  domain: {
    name: "example.com",
    dns: sst.cloudflare.dns()
  }
}

domain.cert?

Type Input<string>

The ARN of an ACM (AWS Certificate Manager) certificate that proves ownership of the domain. By default, a certificate is created and validated automatically.

The certificate will be created in the us-east-1 region as required by AWS AppSync. If you are creating your own certificate, you must also create it in us-east-1.

To manually set up a domain on an unsupported provider, you’ll need to:

Validate that you own the domain by creating an ACM certificate. You can either validate it by setting a DNS record or by verifying an email sent to the domain owner.
Once validated, set the certificate ARN as the cert and set dns to false.
Add the DNS records in your provider to point to the API Gateway URL.

{
  domain: {
    name: "example.com",
    dns: false,
    cert: "arn:aws:acm:us-east-1:112233445566:certificate/3a958790-8878-4cdc-a396-06d95064cf63"
  }
}

domain.dns?

Type Input<false | sst.aws.dns | sst.cloudflare.dns | sst.vercel.dns>

Default sst.aws.dns

The DNS provider to use for the domain. Defaults to the AWS.

Takes an adapter that can create the DNS records on the provider. This can automate validating the domain and setting up the DNS routing.

Supports Route 53, Cloudflare, and Vercel adapters. For other providers, you’ll need to set dns to false and pass in a certificate validating ownership via cert.

Specify the hosted zone ID for the Route 53 domain.

{
  domain: {
    name: "example.com",
    dns: sst.aws.dns({
      zone: "Z2FDTNDATAQYW2"
    })
  }
}

Use a domain hosted on Cloudflare, needs the Cloudflare provider.

{
  domain: {
    name: "example.com",
    dns: sst.cloudflare.dns()
  }
}

Use a domain hosted on Vercel, needs the Vercel provider.

{
  domain: {
    name: "example.com",
    dns: sst.vercel.dns()
  }
}

domain.name

Type Input<string>

The custom domain you want to use.

{
  domain: {
    name: "example.com"
  }
}

Can also include subdomains based on the current stage.

{
  domain: {
    name: `${$app.stage}.example.com`
  }
}

schema

Type Input<string>

Path to the GraphQL schema file. This path is relative to your sst.config.ts.

{
  schema: "schema.graphql",
}

transform?

Type Object

api?
domainName?

Transform how this component creates its underlying resources.

transform.api?

Type GraphQLApiArgs | (args: GraphQLApiArgs, opts: ComponentResourceOptions, name: string) => void

Transform the AppSync GraphQL API resource.

transform.domainName?

Type DomainNameArgs | (args: DomainNameArgs, opts: ComponentResourceOptions, name: string) => void

Transform the AppSync domain name resource.

Properties

id

Type Output<string>

The GraphQL API ID.

nodes

Type Object

api

The underlying resources this component creates.

nodes.api

Type GraphQLApi

The Amazon AppSync GraphQL API.

url

Type Output<string>

The URL of the GraphQL API.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Methods

addDataSource

addDataSource(args)

Parameters

args AppSyncDataSourceArgs
Configure the data source.

Returns AppSyncDataSource

Add a data source to this AppSync API.

Add a Lambda function as a data source.

api.addDataSource({
  name: "lambdaDS",
  lambda: "src/lambda.handler"
});

Customize the Lambda function.

api.addDataSource({
  name: "lambdaDS",
  lambda: {
    handler: "src/lambda.handler",
    timeout: "60 seconds"
  }
});

Add a data source with an existing Lambda function.

api.addDataSource({
  name: "lambdaDS",
  lambda: "arn:aws:lambda:us-east-1:123456789012:function:my-function"
})

Add a DynamoDB table as a data source.

api.addDataSource({
  name: "dynamoDS",
  dynamodb: "arn:aws:dynamodb:us-east-1:123456789012:table/my-table"
})

addFunction

addFunction(args)

Parameters

args AppSyncFunctionArgs
Configure the function.

Returns AppSyncFunction

Add a function to this AppSync API.

Add a function using a Lambda data source.

api.addFunction({
  name: "myFunction",
  dataSource: "lambdaDS",
});

Add a function using a DynamoDB data source.

api.addResolver("Query user", {
  name: "myFunction",
  dataSource: "dynamoDS",
  requestTemplate: `{
    "version": "2017-02-28",
    "operation": "Scan",
  }`,
  responseTemplate: `{
    "users": $utils.toJson($context.result.items)
  }`,
});

addResolver

addResolver(operation, args)

Parameters

operation string
The type and name of the operation.
args AppSyncResolverArgs
Configure the resolver.

Returns AppSyncResolver

Add a resolver to this AppSync API.

Add a resolver using a Lambda data source.

api.addResolver("Query user", {
  dataSource: "lambdaDS",
});

Add a resolver using a DynamoDB data source.

api.addResolver("Query user", {
  dataSource: "dynamoDS",
  requestTemplate: `{
    "version": "2017-02-28",
    "operation": "Scan",
  }`,
  responseTemplate: `{
    "users": $utils.toJson($context.result.items)
  }`,
});

Add a pipeline resolver.

api.addResolver("Query user", {
  functions: [
    "MyFunction1",
    "MyFunction2"
  ]
  code: `
    export function request(ctx) {
      return {};
    }
    export function response(ctx) {
      return ctx.result;
    }
  `,
});

AppSyncDataSourceArgs

dynamodb?

Type Input<string>

The ARN for the DynamoDB table.

{
  dynamodb: "arn:aws:dynamodb:us-east-1:123456789012:table/my-table"
}

elasticSearch?

Type Input<string>

The ARN for the Elasticsearch domain.

{
  elasticSearch: "arn:aws:es:us-east-1:123456789012:domain/my-domain"
}

eventBridge?

Type Input<string>

The ARN for the EventBridge event bus.

{
  eventBridge: "arn:aws:events:us-east-1:123456789012:event-bus/my-event-bus"
}

http?

Type Input<string>

The URL for the HTTP endpoint.

{
  http: "https://api.example.com"
}

lambda?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

The handler for the Lambda function.

{
  lambda: "src/lambda.handler"
}

You can pass in the full function props.

{
  lambda: {
    handler: "src/lambda.handler",
    timeout: "60 seconds"
  }
}

You can also pass in the function ARN.

{
  lambda: "arn:aws:lambda:us-east-1:123456789012:function:my-function"
}

name

Type string

The name of the data source.

{
  name: "lambdaDS"
}

openSearch?

Type Input<string>

The ARN for the OpenSearch domain.

{
  openSearch: "arn:aws:opensearch:us-east-1:123456789012:domain/my-domain"
}

rds?

Type Input<Object>

cluster
credentials

Configure the RDS data source.

{
  rds: {
    cluster: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
    credentials: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret"
  }
}

rds.cluster

Type Input<string>

The ARN for the RDS cluster.

rds.credentials

Type Input<string>

The ARN for the credentials secret store.

transform?

Type Object

dataSource?
serviceRole?

Transform how this component creates its underlying resources.

transform.dataSource?

Type DataSourceArgs | (args: DataSourceArgs, opts: ComponentResourceOptions, name: string) => void

Transform the AppSync DataSource resource.

transform.serviceRole?

Type RoleArgs | (args: RoleArgs, opts: ComponentResourceOptions, name: string) => void

Transform the AppSync DataSource service role resource.

AppSyncFunctionArgs

code?

Type Input<string>

The function code that contains the request and response functions.

{
  code: fs.readFileSync("functions.js")
}

dataSource

Type Input<string>

The data source this resolver is using.

{
  dataSource: "lambdaDS"
}

name

Type string

The name of the AppSync function.

{
  name: "myFunction"
}

requestMappingTemplate?

Type Input<string>

The function request mapping template.

{
  requestTemplate: `{
    "version": "2018-05-29",
    "operation": "Scan",
  }`,
}

responseMappingTemplate?

Type Input<string>

The function response mapping template.

{
  responseTemplate: `{
    "users": $utils.toJson($context.result.items)
  }`,
}

transform?

Type Object

function?

Transform how this component creates its underlying resources.

transform.function?

Type FunctionArgs | (args: FunctionArgs, opts: ComponentResourceOptions, name: string) => void

Transform the AppSync Function resource.

AppSyncResolverArgs

code?

Type Input<string>

The function code that contains the request and response functions.

{
  code: fs.readFileSync("functions.js")
}

dataSource?

Type Input<string>

The data source this resolver is using. This only applies for unit resolvers.

{
  dataSource: "lambdaDS"
}

functions?

Type Input<string[]>

The functions this resolver is using. This only applies for pipeline resolvers.

{
 functions: ["myFunction1", "myFunction2"]
}

kind?

Type Input<“unit” | “pipeline”>

Default “unit”

The type of the resolver.

{
  kind: "pipeline"
}

requestTemplate?

Type Input<string>

For unit resolvers, this is the request mapping template. And for pipeline resolvers, this is the before mapping template.

{
  requestTemplate: `{
    "version": "2017-02-28",
    "operation": "Scan"
  }`
}

responseTemplate?

Type Input<string>

For unit resolvers, this is the response mapping template. And for pipeline resolvers, this is the after mapping template.

{
  responseTemplate: `{
    "users": $utils.toJson($context.result.items)
  }`
}

transform?

Type Object

resolver?

Transform how this component creates its underlying resources.

transform.resolver?

Type ResolverArgs | (args: ResolverArgs, opts: ComponentResourceOptions, name: string) => void

Transform the AppSync Resolver resource.