Skip to content

DEPENDENCIES.md

Latest commit

 

History

History
64 lines (43 loc) · 3.04 KB

DEPENDENCIES.md

File metadata and controls

64 lines (43 loc) · 3.04 KB
Raw

Dependency Guidelines - Strands TypeScript SDK

IMPORTANT: When adding or modifying dependencies, you MUST follow the guidelines in this document. These patterns ensure proper dependency resolution for SDK consumers and avoid version conflicts.

Category When to Use
dependencies Core SDK functionality that users don't interact with directly
peerDependencies Dependencies that cross API boundaries (users construct/pass instances)
devDependencies Build tools, testing frameworks, linters - not shipped to users
peerDependenciesMeta Mark peer dependencies as optional when not all users need them

Peer Dependencies

Peer dependencies are packages the consuming application provides. The SDK relies on the user's installed version, ensuring both operate on the same instance and avoiding version conflicts.

Rule: If a dependency crosses an API boundary, it MUST be a peer dependency.

Example: zod is a peer dependency because users construct Zod schemas and pass them to the SDK:

import { z } from 'zod'
import { Agent, tool } from '@strands-agents/sdk'

const calculator = tool({
  name: 'calculator',
  inputSchema: z.object({ value: z.number() }),
  callback: (input) => input.value * 2,
})

const agent = new Agent({ model, tools: [calculator] })

Mark peer dependencies as optional when not all users need them (e.g., model provider SDKs). Optional peer dependencies must also be added to devDependencies for SDK development and testing.

Package Lock File

The package-lock.json file ensures reproducible builds by locking exact dependency versions.

Command When to Use
npm ci Installing dependencies without changes (fresh clone, after pulling, CI pipelines)
npm install Adding, removing, or updating dependencies

npm ci installs exactly what's in the lock file without modifying it, failing if there's a mismatch. This prevents accidental lock file changes.

When to modify:

  • Adding, removing, or updating dependencies in package.json
  • Running npm audit fix to patch security vulnerabilities

After modifying dependencies, regenerate the lock file for all platforms:

npm run lock:refresh

This generates a lock file that includes platform-specific optional dependencies for Linux, macOS, and Windows (both x64 and arm64), ensuring npm ci works in CI regardless of where the lock file was generated.

Rules:

  1. Never manually edit package-lock.json - always use npm install or npm update
  2. Always run npm run lock:refresh after modifying dependencies to ensure cross-platform compatibility
  3. Commit package-lock.json changes in the same commit as the corresponding package.json changes
  4. If package-lock.json has merge conflicts, delete it and run npm run lock:refresh to regenerate