a2a-js/package.json
ajaynagotha 60899c51e2
feat!: make Express dependency optional for edge environment compatibility (#71)
# fix: make Express dependency optional for edge environment
compatibility

## Summary

- Move A2AExpressApp to separate module at server/express/
- Remove A2AExpressApp from main server exports to avoid forcing Express
import
- Move express to peerDependencies and devDependencies
- Remove unused cors and body-parser dependencies entirely
- Add new package.json export for ./server/express
- Update import statements in samples and documentation
- Enables usage in Cloudflare Workers, Vercel Edge, and other non-Node
environments
- A2AExpressApp uses express.json() which is built into Express, making
body-parser unnecessary
- cors is not used by the library and is an application-level concern
developers should add themselves
- Only express remains as a peerDependency, accurately reflecting actual
requirements

Fixes #69 - Express dependency breaks edge environments

## Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- Important Prefixes for
[release-please](https://github.com/googleapis/release-please):
- `fix:` which represents bug fixes, and correlates to a
[SemVer](https://semver.org/) patch.
- `feat:` represents a new feature, and correlates to a SemVer minor.
- `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking
change (indicated by the `!`) and will result in a SemVer major.
- [x] Ensure the tests and linter pass
- [x] Appropriate docs were updated (if necessary)

Fixes #69 ๐Ÿฆ•

## Problem

The A2A SDK had a hard dependency on Express.js that prevented usage in
edge environments like Cloudflare Workers, Vercel Edge Runtime, and
other platforms that don't support Node.js core APIs.

**Issues identified:**
- ๐Ÿšจ **Hard Express dependency** - `A2AExpressApp` was exported from main
server module, forcing Express import even when not used
- ๐Ÿ“ฆ **Bloated installs** - Express and unused dependencies (cors,
body-parser) were required for all users
- ๐Ÿšซ **Edge incompatibility** - Broke deployment to Cloudflare Workers,
Vercel Edge, and similar platforms
- โšก **Performance impact** - Unnecessary bundle size for non-Express
users
- ๐Ÿ—‘๏ธ **Unused dependencies** - cors and body-parser were listed but not
actually used by the library

## Solution

### 1. Modularized Express Integration
- โœ… Moved `A2AExpressApp` to separate `src/server/express/` module
- โœ… Removed Express exports from main `src/server/index.ts` 
- โœ… Created dedicated export path: `"./server/express"`

### 2. Cleaned Up Dependencies
```json
{
  "dependencies": {
    "uuid": "^11.1.0"
  },
  "peerDependencies": {
    "express": "^4.21.2"
  },
  "devDependencies": {
    "@types/express": "^4.17.23",
    "express": "^4.21.2"
  }
}
```

**Key dependency decisions:**
- โœ… **express**: Required as peerDependency - actually used by
`A2AExpressApp`
- โŒ **body-parser**: Removed entirely - `A2AExpressApp` uses
`express.json()` instead
- โŒ **cors**: Removed entirely - not used by library, application-level
concern

### 3. Updated Package Exports
```json
{
  "./server/express": {
    "types": "./dist/server/express/index.d.ts",
    "import": "./dist/server/express/index.js",
    "require": "./dist/server/express/index.cjs"
  }
}
```

## Breaking Changes & Migration

### Before (โŒ Problematic)
```typescript
import { A2AExpressApp } from "@a2a-js/sdk/server"; // Forces Express dependency
```

### After (โœ… Clean)
```typescript
// Core server functionality (no Express dependency)
import { DefaultRequestHandler, AgentExecutor } from "@a2a-js/sdk/server";

// Express integration (optional, only when needed) 
import { A2AExpressApp } from "@a2a-js/sdk/server/express";
```

**For Express users, install peer dependency:**
```bash
npm install express
```

**For users who need CORS support, add it to your Express app:**
```bash
npm install cors
```

```typescript
import express from 'express';
import cors from 'cors';
import { A2AExpressApp } from "@a2a-js/sdk/server/express";

const app = express();
app.use(cors()); // Add CORS at application level
// ... rest of your Express setup
```

## Benefits

| Benefit | Before | After |
|---------|--------|-------|
| **Edge compatibility** | โŒ Broken | โœ… Works |
| **Bundle size** | ~2MB+ Express deps | Minimal core |
| **Install size** | All deps required | Express optional |
| **Developer experience** | Forced dependency | Explicit choice |
| **Dependency accuracy** | Unused deps included | Only required deps |

## Dependency Analysis

### Why body-parser was removed:
- `A2AExpressApp` uses `express.json()` which is built into Express
4.16+
- No import statements found for `body-parser` in the codebase
- Listing it as a peerDependency forced unnecessary installations

### Why cors was removed:
- No import statements found for `cors` in the codebase  
- CORS is an application-level concern that developers should configure
themselves
- Different applications have different CORS requirements
- Keeping it as a dependency misrepresented the library's actual
requirements

## Testing

- โœ… **All existing tests pass** (15/15)
- โœ… **Build succeeds** with new modular structure
- โœ… **Backward compatibility** maintained for core functionality
- โœ… **Express functionality** preserved when imported from new path

## Files Changed

- **`package.json`** - Updated exports and cleaned up dependency
structure
- **`src/server/index.ts`** - Removed `A2AExpressApp` export
- **`src/server/express/`** - New modular Express integration
- **`README.md`** - Updated import examples
- **`src/samples/agents/movie-agent/index.ts`** - Updated to use new
import paths

## Impact

This change enables the A2A SDK to be used in:
- โœ… Cloudflare Workers
- โœ… Vercel Edge Runtime  
- โœ… Deno Deploy
- โœ… Any edge/serverless environment
- โœ… Traditional Node.js servers (unchanged experience)

The dependency cleanup also:
- ๐ŸŽฏ **Accurately represents requirements** - only lists dependencies
actually used
- ๐Ÿ’ฐ **Reduces install overhead** - consumers don't install unused
packages
- ๐Ÿ”ง **Improves flexibility** - developers choose their own CORS
configuration

---

**Type:** Bug fix  
**Breaking Change:** Minimal (import path only)  
**SemVer:** Patch

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: swapydapy <agarwal.swapy@gmail.com>
2025-08-02 23:06:53 -07:00

84 lines
2.1 KiB
JSON

{
"name": "@a2a-js/sdk",
"version": "0.2.5",
"description": "Server & Client SDK for Agent2Agent protocol",
"repository": "google-a2a/a2a-js.git",
"engines": {
"node": ">=18"
},
"main": "dist/index.js",
"types": "dist/index.d.ts",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./server": {
"types": "./dist/server/index.d.ts",
"import": "./dist/server/index.js",
"require": "./dist/server/index.cjs"
},
"./server/express": {
"types": "./dist/server/express/index.d.ts",
"import": "./dist/server/express/index.js",
"require": "./dist/server/express/index.cjs"
},
"./client": {
"types": "./dist/client/index.d.ts",
"import": "./dist/client/index.js",
"require": "./dist/client/index.cjs"
}
},
"files": [
"dist",
"!dist/**/*.map",
"README.md"
],
"devDependencies": {
"@genkit-ai/googleai": "^1.8.0",
"@genkit-ai/vertexai": "^1.8.0",
"@types/chai": "^5.2.2",
"@types/express": "^4.17.23",
"@types/mocha": "^10.0.10",
"@types/node": "^22.13.14",
"@types/sinon": "^17.0.4",
"c8": "^10.1.3",
"chai": "^5.2.0",
"express": "^4.21.2",
"genkit": "^1.8.0",
"gts": "^6.0.2",
"json-schema-to-typescript": "^15.0.4",
"mocha": "^11.6.0",
"sinon": "^20.0.0",
"tsup": "^8.5.0",
"tsx": "^4.19.3",
"typescript": "^5.8.2"
},
"scripts": {
"clean": "gts clean",
"build": "tsup",
"pretest": "npm run build",
"test": "mocha test/**/*.spec.ts",
"coverage": "c8 npm run test",
"generate": "curl https://raw.githubusercontent.com/google-a2a/A2A/refs/heads/main/specification/json/a2a.json > spec.json && node scripts/generateTypes.js && rm spec.json",
"sample:cli": "tsx src/samples/cli.ts",
"sample:movie-agent": "tsx src/samples/agents/movie-agent/index.ts"
},
"dependencies": {
"uuid": "^11.1.0"
},
"peerDependencies": {
"express": "^4.21.2"
},
"peerDependenciesMeta": {
"express": {
"optional": true
}
},
"mocha": {
"require": "tsx"
}
}