feat!: make Express dependency optional for edge environment compatibility #71

ajaynagotha · 2025-07-27T11:29:25Z

Release-As: 0.3.0

BEGIN_COMMIT_OVERRIDE
feat!: make Express dependency optional
END_COMMIT_OVERRIDE

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:

Follow the CONTRIBUTING Guide.
Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
- Important Prefixes for release-please:
  - fix: which represents bug fixes, and correlates to a SemVer 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.
Ensure the tests and linter pass
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

{
  "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

{
  "./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)

import { A2AExpressApp } from "@a2a-js/sdk/server"; // Forces Express dependency

After (✅ Clean)

// 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:

npm install express

For users who need CORS support, add it to your Express app:

npm install cors

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

- Move A2AExpressApp to separate module at server/express/ - Remove A2AExpressApp from main server exports to avoid forcing Express import - Move express, cors, and body-parser to peerDependencies and devDependencies - 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 Fixes #[issue-number] - Express dependency breaks edge environments

gemini-code-assist

Summary of Changes

Hello @ajaynagotha, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical compatibility issue by refactoring the A2A SDK to make its Express.js integration optional. This change significantly improves the SDK's flexibility, allowing it to be deployed in resource-constrained edge environments like Cloudflare Workers and Vercel Edge, while maintaining full functionality for traditional Node.js users. It achieves this by modularizing the Express-specific components and adjusting dependency management.

Highlights

Dependency Modularization: The A2AExpressApp component, along with its Express.js, CORS, and body-parser dependencies, has been extracted into a separate, optional module (src/server/express/).
Dependency Management: Express.js and related packages are now listed as peerDependencies and devDependencies instead of hard dependencies, making them optional for users who don't require Express integration.
Package Exports: A new package export path (./server/express) has been added to package.json, allowing consumers to explicitly import the Express integration only when needed.
Edge Environment Compatibility: This change resolves a critical issue preventing the SDK from being used in non-Node.js edge environments (e.g., Cloudflare Workers, Vercel Edge) by removing the mandatory Express dependency.
Codebase Updates: Sample code and documentation (README) have been updated to reflect the new import paths for A2AExpressApp, guiding users on how to adopt the modularized approach.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request effectively decouples the Express.js dependency, enabling the SDK to be used in edge environments. The changes are well-structured, moving Express-specific code into a separate module and updating dependencies to be peerDependencies.

My review includes a high-severity comment regarding the breaking nature of these changes and how it should be reflected in the conventional commit message for proper versioning. I've also added a couple of medium-severity comments about code style to ensure consistency.

Overall, great work on making the SDK more modular and versatile!

package.json

src/server/express/a2a_express_app.ts

src/server/express/index.ts

ajaynagotha · 2025-07-27T11:31:05Z

package-lock.json file is not pushed because it will create conflicts. let me know

Resolve linting issues Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

ajaynagotha · 2025-07-27T11:37:09Z

/gemini review

gemini-code-assist

Code Review

This pull request modularizes the Express.js dependency, improving compatibility with edge environments. The changes to package.json and module exports are well-structured, and the documentation has been updated. The feedback focuses on refining the package dependencies to ensure that users are not required to install unnecessary packages, aligning with the goal of making the SDK more lightweight and modular.

package.json

- Remove cors and body-parser from both devDependencies and peerDependencies - A2AExpressApp uses express.json() which is built into Express, making body-parser unnecessary - cors is an application-level concern that developers should add to their Express app if needed - These dependencies were forcing unnecessary installations for package consumers - Only express remains as a peerDependency, accurately reflecting actual requirements

…ajaynagotha/a2a-js into fix-optional-express-dependency

ajaynagotha · 2025-07-27T11:45:21Z

/gemini review

gemini-code-assist

Code Review

This pull request effectively decouples the Express.js dependency, enabling the SDK to be used in edge environments. The changes are well-structured, moving Express-specific code into a separate, optional module. My review focuses on ensuring consistency between the implementation and the detailed pull request description, particularly regarding dependency management in package.json. I've also included a couple of minor suggestions to adhere to file formatting best practices.

package.json

src/server/express/a2a_express_app.ts

src/server/express/index.ts

Fix liniting issues Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Fix linting issues Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

ajaynagotha · 2025-07-27T11:50:35Z

/gemini review

gemini-code-assist

Code Review

This pull request effectively makes the Express dependency optional, which is a great step towards compatibility with edge environments. The refactoring is clean, moving Express-specific code into a separate, optional module. The changes to package.json are correct, and the documentation updates are clear. Adding peerDependenciesMeta to package.json to prevent installation warnings for users who don't need Express would complete the goal of making it truly optional from a developer experience perspective.

package.json

Add peerDependenciesMeta to mark express as optional, preventing package manager warnings when express is not installed. This improves developer experience for users in non-Node/edge environments where express is not needed.

…ajaynagotha/a2a-js into fix-optional-express-dependency

ajaynagotha · 2025-07-27T12:43:30Z

/gemini review

gemini-code-assist

Code Review

This pull request makes the Express dependency optional, which enables the SDK to be used in edge environments. The changes are well-structured, and the PR description is clear. The installation instructions in the README.md should be updated to reflect that express is now a peer dependency.

README.md

ajaynagotha · 2025-07-27T12:51:39Z

/gemini review

gemini-code-assist

Code Review

This pull request effectively refactors the project to make the Express.js dependency optional, which is a great improvement for supporting edge environments. The changes are well-structured, moving Express-specific code into a separate module and updating package.json accordingly. The documentation and sample code have also been correctly updated to reflect these changes.

My main concern is with the package versions specified in package.json. Several of the specified versions for express and @types/express do not exist on the public npm registry, which will cause installation failures. I've left specific comments with suggestions for valid versions. Once those are addressed, this PR will be in excellent shape.

package.json

ajaynagotha · 2025-07-27T12:58:19Z

/gemini summary

- Add Express peer dependency installation instructions to README - Include note in A2A Server section about Express requirement - Prevents runtime errors when using A2AExpressApp without Express

gemini-code-assist · 2025-07-27T12:58:51Z

Summary of Changes

This pull request significantly refactors the SDK's server-side architecture to enhance compatibility with edge and serverless environments. It achieves this by decoupling the A2AExpressApp from the core server exports, making the Express dependency optional, and meticulously cleaning up unused cors and body-parser packages. This change reduces the library's footprint for non-Express users and provides greater flexibility for deployment across diverse runtime environments.

Highlights

Modularized Express Integration: The A2AExpressApp class has been moved from the main server module (src/server/index.ts) to a new, dedicated module at src/server/express/. This makes the Express integration optional and allows for a cleaner separation of concerns.
Refined Dependency Management: The express package is now a peerDependency (and devDependency), reflecting its optional nature for users who only need core server functionality. Crucially, cors and body-parser have been entirely removed from the project's dependencies, as they were not directly used by the library and are considered application-level concerns.
Edge Environment Compatibility: By making Express optional and removing unnecessary dependencies, the SDK can now be used in various edge and serverless environments like Cloudflare Workers and Vercel Edge Runtime, which previously caused issues due to Node.js core API dependencies.
Updated Package Exports and Imports: A new export path (./server/express) has been added to package.json for the optional Express integration. Corresponding import statements in README.md and sample files have been updated to reflect this change.

Changelog

README.md
- Updated the example import statement for A2AExpressApp to use the new modular path (@a2a-js/sdk/server/express).
package.json
- Introduced a new exports entry for ./server/express to provide a dedicated entry point for the optional Express integration.
- Relocated express from dependencies to peerDependencies and devDependencies, making it an optional dependency for consumers.
- Removed cors, @types/cors, body-parser, and @types/body-parser from dependencies, aligning with the goal of removing unused dependencies entirely.
- Added peerDependenciesMeta to explicitly mark express as an optional peer dependency, preventing installation warnings for non-Express users.
src/samples/agents/movie-agent/index.ts
- Modified the import statement for A2AExpressApp to point to its new location (../../../server/express/index.js).
src/server/a2a_express_app.ts
- This file was renamed and moved to src/server/express/a2a_express_app.ts.
- Internal import paths within the file were adjusted to reflect the new directory structure.
src/server/express/index.ts
- A new file was created to serve as the entry point for the Express-specific module, exporting A2AExpressApp.
src/server/index.ts
- The export of A2AExpressApp was removed from this main server entry point.

Activity

The author, ajaynagotha, initiated multiple /gemini review requests and a /gemini summary request.
ajaynagotha responded to several review comments, indicating that fixes were applied, such as updating the PR title to reflect a breaking change, removing cors and body-parser from dependencies, updating the description, implementing peerDependenciesMeta, and improving README.md instructions.
gemini-code-assist[bot] provided extensive feedback throughout the review process, including highlighting that moving express to peerDependencies is a breaking change and suggesting a fix!: commit message.
gemini-code-assist[bot] identified trailing spaces and missing newlines in newly added/moved files.
gemini-code-assist[bot] strongly recommended the removal of cors and body-parser from peerDependencies and devDependencies due to them being unused or application-level concerns.
gemini-code-assist[bot] pointed out a discrepancy between the PR description and package.json regarding cors and body-parser in peerDependencies.
gemini-code-assist[bot] suggested the addition of peerDependenciesMeta to mark express as optional.
gemini-code-assist[bot] advised to update README.md with installation instructions for express for users of A2AExpressApp.
There are still unresolved comments from gemini-code-assist[bot] regarding invalid versions for @types/express (^4.17.23) and express (^4.21.2) in devDependencies and peerDependencies, suggesting ^4.17.24 and ^4.19.2 respectively.

ydennisy · 2025-07-28T12:15:28Z

@ajaynagotha this looks great! Hopefully the team can get this merged soon :)

Would be great to also add a small example showing how the new approach allows the usage of something like Hono for serving the requests.

ajaynagotha · 2025-07-28T13:22:28Z

@ajaynagotha this looks great! Hopefully the team can get this merged soon :)

Would be great to also add a small example showing how the new approach allows the usage of something like Hono for serving the requests.

Sure I will try to present code example

ajaynagotha · 2025-08-03T06:27:02Z

@swapydapy Thank you for reviewing and merging this! Getting contributions accepted really motivates me to keep contributing to the project and the community.