Registry / aws / serverless-appsync-plugin

serverless-appsync-plugin

JSON →
library2.10.5jsnpmunverified

The `serverless-appsync-plugin` extends the Serverless Framework to enable seamless deployment and management of AWS AppSync GraphQL APIs. Currently at stable version 2.10.5, the plugin receives regular updates, including bug fixes and new features, with several minor releases in late 2025. It differentiates itself by offering deep integration into the Serverless ecosystem, allowing developers to define AppSync schemas, data sources (Lambda, DynamoDB, HTTP, RDS, None), resolvers (VTL and JavaScript), authentication methods (API_KEY, AWS_IAM, AMAZON_COGNITO_USER_POOLS, OPENID_CONNECT), custom domains, caching, and Web Application Firewall (WAF) configurations directly within their `serverless.yml` or `serverless.ts` files. This declarative approach significantly simplifies the provisioning and updating of complex AppSync infrastructure, providing CLI commands and exposing CloudFormation variables for easy referencing of deployed resources.

awsdevops
github ↗package ↗
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

This package is a Serverless Framework plugin and is activated by listing its name in the 'plugins' section of your `serverless.yml` or `serverless.ts` configuration file. It does not export symbols for direct programmatic import into application code.

plugins: - serverless-appsync-plugin

The 'appSync' top-level property within your Serverless configuration file is where you define your AppSync API's name, authentication, schema path, data sources, resolvers, and other related settings. In v2, this block moved directly under the root of `serverless.yml` from `custom.appSync` in v1.

// in serverless.yml or serverless.ts appSync: name: my-api authentication: type: API_KEY schema: schema.graphql # ... define dataSources, resolvers, etc.

The plugin exports several variables (e.g., `id`, `url`, `arn`, `apiKey.[NAME]`) that can be referenced in your `serverless.yml` or `serverless.ts` for dynamic values generated during CloudFormation deployment.

provider: environment: APPSYNC_ID: ${appsync:id} APPSYNC_URL: ${appsync:url} APPSYNC_API_KEY: ${appsync:apiKey.myKey}

This quickstart demonstrates a minimal Serverless.ts configuration using the plugin to deploy an AppSync API with an API key, a basic GraphQL schema, a Lambda data source, and a resolver. It sets up a 'hello' query backed by a Lambda function. To run this, you would also need a `schema.graphql` file and a `src/handlers/hello.handler` function.

import type { AWS } from '@serverless/typescript'; const serverlessConfiguration: AWS = { service: 'my-appsync-service', frameworkVersion: '3', plugins: [ 'serverless-appsync-plugin' ], provider: { name: 'aws', runtime: 'nodejs18.x', region: 'us-east-1', stage: 'dev', environment: { AWS_REGION: '${aws:region}', } }, appSync: { name: '${self:service}-${sls:stage}-api', authentication: { type: 'API_KEY', }, schema: 'schema.graphql', // Ensure this file exists at the root resolvers: { 'Query.hello': { dataSource: 'helloLambda', }, }, dataSources: { helloLambda: { type: 'AWS_LAMBDA', config: { functionName: 'hello', }, }, }, apiKeys: [ { name: 'defaultApiKey', }, ], }, functions: { hello: { handler: 'src/handlers/hello.handler', // Ensure this file and handler exist events: [ { http: { method: 'get', path: '/hello', }, }, ], }, }, }; module.exports = serverlessConfiguration;
serverless --version
Debug
Known footguns
breakingUpgrading from v1.x to v2.x involves significant breaking changes, including API configuration structure changes and dropped support for multiple AppSync APIs per stack. API keys may also be rotated on the first v2 deployment.
gotchaThe plugin requires Node.js v16 or higher. Using older Node.js versions will lead to installation and runtime errors.
gotchaThis plugin has a peer dependency on Serverless Framework v3.0.0 or higher. While v2.8.0 introduced support for Serverless v4, older plugin versions (before v2.8.0) may not be compatible with Serverless v4, and no plugin version is compatible with Serverless v2.
deprecatedAs of Serverless Framework v4 (and potentially earlier versions with built-in AppSync support), the core framework now includes native AppSync integration. This means the `serverless-appsync-plugin` might no longer be strictly necessary and could potentially conflict with the built-in functionality.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
0 hits · last 30 days

No traffic data recorded yet.

Resources
githubhttps://github.com/sid88in/serverless-appsync-plugin ↗
packagehttps://www.npmjs.com/package/serverless-appsync-plugin ↗