Getting Started

Installation

Install appsync-local globally or use npx:

# Global installation
npm install -g appsync-local-server

# Or use with npx (no installation needed)
npx appsync-local-server start

Project Setup

Create the following files in your project:

1. GraphQL Schema (schema.graphql)

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

type Query {
  getUser(id: ID!): User
  listUsers: [User]
}

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

2. Configuration File (appsync-config.json)

{
  "schema": "schema.graphql",
  "port": 4000,
  "apiConfig": {
    "auth": [
      { "type": "API_KEY", "key": "da2-local-api-key" }
    ]
  },
  "dataSources": [
    {
      "name": "UsersTable",
      "type": "DYNAMODB",
      "config": {
        "tableName": "Users",
        "region": "us-east-1"
      }
    }
  ],
  "resolvers": [
    {
      "type": "Query",
      "field": "getUser",
      "kind": "Unit",
      "dataSource": "UsersTable",
      "file": "resolvers/getUser.js"
    },
    {
      "type": "Query",
      "field": "listUsers",
      "kind": "Unit",
      "dataSource": "UsersTable",
      "file": "resolvers/listUsers.js"
    },
    {
      "type": "Mutation",
      "field": "createUser",
      "kind": "Unit",
      "dataSource": "UsersTable",
      "file": "resolvers/createUser.js"
    }
  ]
}

3. Resolver (resolvers/getUser.js)

export function request(ctx) {
  return {
    operation: 'GetItem',
    key: {
      id: { S: ctx.arguments.id }
    }
  };
}

export function response(ctx) {
  return ctx.result;
}

Running the Server

# Start with default config file (appsync-config.json)
appsync-local start

# Or specify a config file
appsync-local start -c my-config.json

# Specify a custom port
appsync-local start -p 5000

Testing Your API

Once the server is running, you can test it with curl or any GraphQL client:

# Query example
curl -X POST http://localhost:4000 \
  -H "Content-Type: application/json" \
  -H "x-api-key: da2-local-api-key" \
  -d '{"query": "{ getUser(id: \"123\") { id name email } }"}'

Writing Resolvers

AppSync JavaScript resolvers have two functions:

• request(ctx) - Transform the GraphQL request into a data source operation
• response(ctx) - Transform the data source response back to GraphQL

Context Object (ctx)

The context object contains:

Property	Description
ctx.arguments	GraphQL field arguments
ctx.source	Parent object (for nested resolvers)
ctx.identity	Caller identity information
ctx.request	Request metadata (headers, etc.)
ctx.stash	Shared data between pipeline functions
ctx.prev	Previous function result (pipeline only)
ctx.result	Data source result (in response function)
ctx.util	Utility functions

Next Steps

• Configuration Reference - Full config options
• Data Sources - DynamoDB, Lambda, HTTP, RDS