AppSync

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.

Tip

Built-in support for AWS Route 53, Cloudflare, and Vercel. And manual setup for other providers.

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.

Tip

You need to pass in a cert for domains that are not hosted on supported dns providers.

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

1. 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.
2. Once validated, set the certificate ARN as the cert and set dns to false.
3. 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 => void)

Transform the AppSync GraphQL API resource.

transform.domainName?

Type DomainNameArgs | (args: DomainNameArgs => 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

The following are accessible through the SDK at runtime.

Links

• url string

  The URL of the GraphQL API.

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

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

elasticSearch?

Type Input<string>

The ARN for the Elasticsearch domain.

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

eventBridge?

Type Input<string>

The ARN for the EventBridge event bus.

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

http?

Type Input<string>

The URL for the HTTP endpoint.

{
  name: "httpDS",
  http: "https://api.example.com"
}

lambda?

Type Input<string | FunctionArgs>

The ARN for the Lambda function.

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

name

Type string

The name of the data source.

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

openSearch?

Type Input<string>

The ARN for the OpenSearch domain.

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

rds?

Type Input<Object>

• cluster

• credentials

Configuring RDS data source.

{
  name: "rdsDS",
  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 => void)

Transform the AppSync DataSource resource.

transform.serviceRole?

Type RoleArgs | (args: RoleArgs => 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. This only applies for “unit” resolvers.

{
  dataSource: "lambdaDS"
}

name

Type string

The name of the AppSync function.

{
  name: "myFunction",
}

requestMappingTemplate?

Type Input<string>

The function request mapping template.

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

responseMappingTemplate?

Type Input<string>

The function response mapping template.

{
  dataSource: "dynamoDS",
  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 => 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.

{
  dataSource: "dynamoDS",
  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.

{
  dataSource: "dynamoDS",
  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 => void)

Transform the AppSync Resolver resource.