DynamoDB with Serverless Framework: API and Local Setup

Define DynamoDB tables in the resources block of serverless.yml, then pass each table name and the required IAM permissions to your Lambda functions. Serverless Framework deploys the table through CloudFormation alongside the API. The example below uses Framework v4, Node.js 24 and AWS SDK for JavaScript v3 to create, list and delete animals.

Why use DynamoDB with Serverless Framework?

Lambda and DynamoDB remove server provisioning from this application. Framework connects API Gateway routes, Lambda handlers, IAM roles and the table in one deployment. DynamoDB on-demand capacity bills for requests, while storage and optional features such as backups have their own charges. A quiet application is not necessarily free.

Framework v4 requires authentication through the Dashboard or a license key. It is free for individuals and organizations at or below $2 million in annual revenue; organizations above that threshold need a paid subscription. Framework licensing is separate from your AWS bill. Check the v4 upgrade and licensing guide when adopting it. Framework v3 is no longer maintained.

If you want AWS's own template extension and local Lambda tooling, compare AWS SAM. If you prefer TypeScript resource linking, compare SST. Both can work with DynamoDB, but their configuration and deployment engines differ.

Step 1: create a project

Use a supported Node.js installation, AWS CLI v2 and an AWS profile. Check the account before deploying:

export AWS_PROFILE=development
aws sts get-caller-identity
node --version
mkdir animals-api
cd animals-api
npm init -y
npm install --save-dev serverless@4
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npx serverless login
export AWS_PROFILE=development
aws sts get-caller-identity
node --version
mkdir animals-api
cd animals-api
npm init -y
npm install --save-dev serverless@4
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npx serverless login

The login authenticates the Framework CLI; your AWS credentials authorize deployment. Teams using a license key should follow the vendor's private credential configuration instead of committing it. Create serverless.yml and handler.mjs in this directory. No archived template repository is needed.

Step 2: define the table, routes and permissions

Use this complete serverless.yml:

service: animals-api
frameworkVersion: "4"

provider:
  name: aws
  runtime: nodejs24.x
  region: us-east-1
  stage: dev
  environment:
    TABLE_NAME: ${self:service}-${sls:stage}-animals
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:PutItem
            - dynamodb:Scan
            - dynamodb:DeleteItem
          Resource:
            Fn::GetAtt: [AnimalsTable, Arn]

build:
  esbuild: false

functions:
  createAnimal:
    handler: handler.create
    events:
      - httpApi:
          path: /animals
          method: POST
  getAnimals:
    handler: handler.list
    events:
      - httpApi:
          path: /animals
          method: GET
  deleteAnimal:
    handler: handler.remove
    events:
      - httpApi:
          path: /animals/{name}
          method: DELETE

resources:
  Resources:
    AnimalsTable:
      Type: AWS::DynamoDB::Table
      DeletionPolicy: Retain
      UpdateReplacePolicy: Retain
      Properties:
        TableName: ${self:provider.environment.TABLE_NAME}
        BillingMode: PAY_PER_REQUEST
        DeletionProtectionEnabled: true
        AttributeDefinitions:
          - AttributeName: name
            AttributeType: S
        KeySchema:
          - AttributeName: name
            KeyType: HASH
        PointInTimeRecoverySpecification:
          PointInTimeRecoveryEnabled: true
          RecoveryPeriodInDays: 14
service: animals-api
frameworkVersion: "4"

provider:
  name: aws
  runtime: nodejs24.x
  region: us-east-1
  stage: dev
  environment:
    TABLE_NAME: ${self:service}-${sls:stage}-animals
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:PutItem
            - dynamodb:Scan
            - dynamodb:DeleteItem
          Resource:
            Fn::GetAtt: [AnimalsTable, Arn]

build:
  esbuild: false

functions:
  createAnimal:
    handler: handler.create
    events:
      - httpApi:
          path: /animals
          method: POST
  getAnimals:
    handler: handler.list
    events:
      - httpApi:
          path: /animals
          method: GET
  deleteAnimal:
    handler: handler.remove
    events:
      - httpApi:
          path: /animals/{name}
          method: DELETE

resources:
  Resources:
    AnimalsTable:
      Type: AWS::DynamoDB::Table
      DeletionPolicy: Retain
      UpdateReplacePolicy: Retain
      Properties:
        TableName: ${self:provider.environment.TABLE_NAME}
        BillingMode: PAY_PER_REQUEST
        DeletionProtectionEnabled: true
        AttributeDefinitions:
          - AttributeName: name
            AttributeType: S
        KeySchema:
          - AttributeName: name
            KeyType: HASH
        PointInTimeRecoverySpecification:
          PointInTimeRecoveryEnabled: true
          RecoveryPeriodInDays: 14

The stage-specific name keeps development and production tables separate. You can instead use Ref: AnimalsTable for the environment variable when CloudFormation generates the physical name; the explicit name here also makes local setup predictable.

provider.iam.role.statements grants exactly the data operations used below on this table. It does not grant schema-management permissions to the application. All three functions share this role in the example; separate per-function roles can narrow access further. If you later Query a GSI, add dynamodb:Query and its index ARN as well.

The resources block accepts normal CloudFormation resources. Backups, TTL, indexes, resource policies and throughput caps use the same properties as the CloudFormation examples. Only key attributes belong in AttributeDefinitions; do not declare every field an animal might contain.

The example disables the v4 esbuild integration and packages ordinary JavaScript with production dependencies. handler.mjs is already an ES module. Inspect the packaged ZIP to confirm both SDK packages are present, rather than relying on the runtime's bundled SDK version. Framework also supports built-in bundling; see its build configuration.

Step 3: write the SDK v3 handlers

Start handler.mjs with the shared client. A local endpoint is used only when serverless-offline sets IS_OFFLINE:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient,
  PutCommand,
  ScanCommand,
  DeleteCommand,
} from "@aws-sdk/lib-dynamodb"

const client = new DynamoDBClient(process.env.IS_OFFLINE === "true" ? {
  region: "us-east-1",
  endpoint: "http://127.0.0.1:8000",
  credentials: { accessKeyId: "local", secretAccessKey: "local" },
} : {})
const db = DynamoDBDocumentClient.from(client)
const TableName = process.env.TABLE_NAME
const response = (statusCode, data) => ({
  statusCode,
  headers: { "content-type": "application/json" },
  body: JSON.stringify(data),
})
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient,
  PutCommand,
  ScanCommand,
  DeleteCommand,
} from "@aws-sdk/lib-dynamodb"

const client = new DynamoDBClient(process.env.IS_OFFLINE === "true" ? {
  region: "us-east-1",
  endpoint: "http://127.0.0.1:8000",
  credentials: { accessKeyId: "local", secretAccessKey: "local" },
} : {})
const db = DynamoDBDocumentClient.from(client)
const TableName = process.env.TABLE_NAME
const response = (statusCode, data) => ({
  statusCode,
  headers: { "content-type": "application/json" },
  body: JSON.stringify(data),
})

The local credentials are dummy signing values for DynamoDB Local. Deployed functions use their execution role. Do not leave a local endpoint in production configuration.

Create an animal

Append this handler. It validates the key and rejects a duplicate name instead of silently replacing an existing item:

export const create = async (event) => {
  let item
  try {
    const body = event.isBase64Encoded
      ? Buffer.from(event.body, "base64").toString("utf8")
      : event.body
    item = JSON.parse(body)
  } catch {
    return response(400, { message: "Body must be JSON" })
  }
  if (typeof item?.name !== "string" || !item.name.trim()) {
    return response(400, { message: "name must be a nonempty string" })
  }
  if (Buffer.byteLength(item.name, "utf8") > 2048) {
    return response(400, { message: "name is too long for a partition key" })
  }
  try {
    await db.send(new PutCommand({
      TableName,
      Item: item,
      ConditionExpression: "attribute_not_exists(#name)",
      ExpressionAttributeNames: { "#name": "name" },
    }))
    return response(201, item)
  } catch (error) {
    if (error.name === "ConditionalCheckFailedException") {
      return response(409, { message: "An animal with this name already exists" })
    }
    throw error
  }
}
export const create = async (event) => {
  let item
  try {
    const body = event.isBase64Encoded
      ? Buffer.from(event.body, "base64").toString("utf8")
      : event.body
    item = JSON.parse(body)
  } catch {
    return response(400, { message: "Body must be JSON" })
  }
  if (typeof item?.name !== "string" || !item.name.trim()) {
    return response(400, { message: "name must be a nonempty string" })
  }
  if (Buffer.byteLength(item.name, "utf8") > 2048) {
    return response(400, { message: "name is too long for a partition key" })
  }
  try {
    await db.send(new PutCommand({
      TableName,
      Item: item,
      ConditionExpression: "attribute_not_exists(#name)",
      ExpressionAttributeNames: { "#name": "name" },
    }))
    return response(201, item)
  } catch (error) {
    if (error.name === "ConditionalCheckFailedException") {
      return response(409, { message: "An animal with this name already exists" })
    }
    throw error
  }
}

A Put without the condition overwrites an item with the same key. Decide whether the application should reject, replace or update duplicates, and express that choice explicitly. Add a full request schema and size validation for your own fields before accepting arbitrary user data.

List animals with a continuation token

Append this handler. Scan reads a page, not necessarily the whole table:

export const list = async (event) => {
  let ExclusiveStartKey
  const token = event.queryStringParameters?.nextToken
  if (token) {
    try {
      const key = JSON.parse(Buffer.from(token, "base64url").toString("utf8"))
      if (typeof key?.name !== "string" || !key.name) throw new Error("Invalid key")
      ExclusiveStartKey = { name: key.name }
    } catch {
      return response(400, { message: "Invalid nextToken" })
    }
  }
  const result = await db.send(new ScanCommand({
    TableName,
    Limit: 100,
    ExclusiveStartKey,
  }))
  return response(200, {
    items: result.Items ?? [],
    nextToken: result.LastEvaluatedKey
      ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString("base64url")
      : null,
  })
}
export const list = async (event) => {
  let ExclusiveStartKey
  const token = event.queryStringParameters?.nextToken
  if (token) {
    try {
      const key = JSON.parse(Buffer.from(token, "base64url").toString("utf8"))
      if (typeof key?.name !== "string" || !key.name) throw new Error("Invalid key")
      ExclusiveStartKey = { name: key.name }
    } catch {
      return response(400, { message: "Invalid nextToken" })
    }
  }
  const result = await db.send(new ScanCommand({
    TableName,
    Limit: 100,
    ExclusiveStartKey,
  }))
  return response(200, {
    items: result.Items ?? [],
    nextToken: result.LastEvaluatedKey
      ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString("base64url")
      : null,
  })
}

Call again with nextToken until it is null. This is a small catalog example, not a recommended access pattern for every application. For per-owner lists or large datasets, design a partition key or index that supports Query. A continuation token is not authentication, and Scan does not provide a consistent snapshot across pages.

Delete an animal

Append the final handler:

export const remove = async (event) => {
  const name = event.pathParameters?.name
  if (typeof name !== "string" || !name) {
    return response(400, { message: "name is required" })
  }
  await db.send(new DeleteCommand({ TableName, Key: { name } }))
  return { statusCode: 204, body: "" }
}
export const remove = async (event) => {
  const name = event.pathParameters?.name
  if (typeof name !== "string" || !name) {
    return response(400, { message: "name is required" })
  }
  await db.send(new DeleteCommand({ TableName, Key: { name } }))
  return { statusCode: 204, body: "" }
}

DeleteItem succeeds even when the item is absent, making this delete naturally repeatable. Add a condition if the application must distinguish missing items, and enforce ownership in the handler before allowing users to delete records.

Step 4: package, deploy and test

npx serverless print --stage dev
npx serverless package --stage dev
npx serverless deploy --stage dev
npx serverless print --stage dev
npx serverless package --stage dev
npx serverless deploy --stage dev

Inspect the generated CloudFormation and packaged functions before deployment. Use the printed HTTP API URL for these requests:

export API_URL=https://your-api-id.execute-api.us-east-1.amazonaws.com
curl -X POST "$API_URL/animals" -H 'Content-Type: application/json' \
  -d '{"name":"otter","habitat":"river"}'
curl "$API_URL/animals"
curl -X DELETE "$API_URL/animals/otter"
export API_URL=https://your-api-id.execute-api.us-east-1.amazonaws.com
curl -X POST "$API_URL/animals" -H 'Content-Type: application/json' \
  -d '{"name":"otter","habitat":"river"}'
curl "$API_URL/animals"
curl -X DELETE "$API_URL/animals/otter"

Check the duplicate-create response and follow pagination with enough test data to require another page. Function logs and DynamoDB metrics should show successful calls without unexpected throttles.

These routes are public demonstration endpoints. Before serving real users, add an authorizer, derive identity from verified claims, validate request fields and enforce per-item permissions. Scoped Lambda IAM limits which AWS resources the function can touch; it does not authenticate the person calling the HTTP API.

Local development with serverless-dynamodb

Use the maintained serverless-dynamodb plugin, a continuation of serverless-dynamodb-local. The older package has not had an npm release since 2021. The replacement README still lists Framework v1 through v3, so test its compatibility with your pinned v4 release rather than assuming formal v4 support.

Install it alongside serverless-offline and add these top-level settings:

npm install --save-dev serverless-dynamodb serverless-offline
npm install --save-dev serverless-dynamodb serverless-offline

plugins:
  - serverless-dynamodb
  - serverless-offline

custom:
  serverless-dynamodb:
    stages:
      - dev
    start:
      docker: true
      dockerImage: amazon/dynamodb-local:3.3.2
      port: 8000
      inMemory: true
      migrate: true
plugins:
  - serverless-dynamodb
  - serverless-offline

custom:
  serverless-dynamodb:
    stages:
      - dev
    start:
      docker: true
      dockerImage: amazon/dynamodb-local:3.3.2
      port: 8000
      inMemory: true
      migrate: true

Keep the DynamoDB plugin before serverless-offline. With Docker running, start local development:

npx serverless offline start --stage dev
npx serverless offline start --stage dev

The plugin creates local tables from the resources definitions. inMemory: true discards data when stopped; use persistent storage when retaining local fixtures matters. If you use its Java mode instead, current DynamoDB Local requires JRE 17 or newer, despite the plugin README's older Java 11 requirement.

Local testing does not prove IAM, PITR, TTL cleanup, global replication or production throughput behavior. If a plugin version is incompatible, run Docker directly and create the table with the CLI as shown in running DynamoDB locally. Point the SDK at that endpoint explicitly.

Monitoring, retention and existing boilerplates

Monitor Lambda errors and latency, API errors, table throttles and GSI backfill. The SDK retries eligible transient failures, but your application still needs an idempotency strategy for operations that may be repeated. A failed response does not always mean the write did not happen.

serverless remove removes the application's stack, but the template's retention policies preserve this table. Deletion protection additionally blocks a direct table deletion. Document who owns retained tables and how they are backed up; they continue to incur charges after the application is removed.

The older Dynobase API boilerplate is useful as historical context, not a substitute for checking current SDK, runtime and Framework dependencies. Review its versions and authorization model before reuse. For a database shared by several services, consider managing it independently with Terraform and granting each application's role the necessary access.