Add Koa framework integration package #455

dahlia · 2025-10-05T06:45:42Z

Summary

Adds support for the Koa web framework through a dedicated @fedify/koa integration package.

Closes #454

Changes

Package Implementation (`packages/koa/`)

Implements createMiddleware() function for Koa integration
Supports both Koa v2.x and v3.x via peer dependencies (^2.0.0 || ^3.0.0)
Converts between Koa's context-based API and Web Standards Request/Response
Handles onNotFound/onNotAcceptable callbacks for proper routing integration
Builds for both npm (ESM/CJS) and JSR distribution

Key Features

Context conversion: Transforms Koa's ctx object to/from Web Standards API
Stream handling: Properly converts response body streams for Koa
Async middleware: Fully compatible with Koa's async/await middleware pattern
Version compatibility: Works with both Koa 2.x (latest: 2.16.2) and 3.x (latest: 3.0.1)

Example Project (`examples/koa/`)

Basic Koa app with Fedify integration
Actor and Note dispatchers demonstration
Context data factory usage example
README with setup and running instructions

Documentation

Added Koa section to docs/manual/integration.md
Positioned after Express (both are Node.js ecosystem frameworks)
Installation instructions for all package managers (Deno, npm, pnpm, Yarn, Bun)
Code example with TypeScript

Configuration Updates

Added packages/koa and examples/koa to pnpm-workspace.yaml
Added packages/koa to Deno workspace in deno.json
Updated catalog to use koa: ^2.16.0 (latest stable 2.x version)
Added @types/koa: ^2.15.0 to catalog

Testing

✅ Builds successfully with tsdown (ESM/CJS)
✅ Passes Deno formatting, linting, and type checking
✅ All pre-commit hooks passed

API Example

import Koa from "koa";
import { createMiddleware } from "@fedify/koa";
import { createFederation } from "@fedify/fedify";

const federation = createFederation<void>({
  kv: new MemoryKvStore(),
});

const app = new Koa();
app.proxy = true;

app.use(createMiddleware(federation, (ctx) => {
  // Pass Koa context data to Fedify handlers
  return { user: ctx.state.user, db: ctx.db };
}));

Notes

The implementation follows the same patterns as existing integrations (@fedify/express, @fedify/hono)
Uses deno-lint-ignore comments for necessary any types (required for framework agnosticism)
Koa's middleware architecture (async functions with ctx and next) is well-supported

Implements @fedify/koa package to integrate Fedify with Koa v2.x and v3.x. - Add packages/koa with createMiddleware() function - Support both Koa 2.x and 3.x via peer dependencies - Convert between Koa context and Web Standards Request/Response - Handle onNotFound/onNotAcceptable callbacks for routing - Build for both npm (ESM/CJS) and JSR distribution - Add examples/koa with basic integration demo - Update documentation with Koa integration guide - Update catalog to use Koa 2.16.0 (latest 2.x) Closes fedify-dev#454 Co-Authored-By: Claude <[email protected]>

gemini-code-assist · 2025-10-05T06:46:04Z

Summary of Changes

Hello @dahlia, 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 significantly expands Fedify's integration capabilities by introducing a dedicated package for the Koa web framework. This new integration allows developers to easily incorporate Fedify's federation features into their Koa applications, providing robust context conversion, stream handling, and full compatibility with Koa's async middleware pattern across both Koa v2.x and v3.x. The addition includes a new package, an example project, and updated documentation to guide users through the setup and usage.

Highlights

New Koa Integration Package: Introduced @fedify/koa to seamlessly integrate Fedify with Koa web applications, supporting both Koa v2.x and v3.x.
Koa Middleware Functionality: Implements a createMiddleware() function for Koa, handling context conversion between Koa's ctx object and Web Standards Request/Response, and managing onNotFound/onNotAcceptable callbacks.
Comprehensive Documentation and Example: Includes a new section in the manual (docs/manual/integration.md), a dedicated example project (examples/koa/), and updated configuration files to guide users through setup and usage.

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 by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

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 pull request 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. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

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 introduces a new integration package, @fedify/koa, to support the Koa web framework. The implementation is well-structured, following patterns from existing framework integrations and includes comprehensive changes across the repository, such as documentation, examples, and configuration updates. The code correctly handles conversions between Koa's context and Web Standards Request/Response objects, including stream handling. My review includes a couple of suggestions to improve code clarity and make the example more illustrative for users.

packages/koa/src/index.ts

examples/koa/index.ts

Copilot

Pull Request Overview

This pull request adds comprehensive support for the Koa web framework through a new @fedify/koa integration package, allowing Fedify to work seamlessly with Koa applications.

Implements createMiddleware() function for Koa integration with support for both v2.x and v3.x
Adds proper conversion between Koa's context-based API and Web Standards Request/Response
Includes complete example project and documentation updates

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`pnpm-workspace.yaml`	Adds Koa package and example to workspace configuration
`packages/koa/src/index.ts`	Core integration logic with context conversion and middleware creation
`packages/koa/package.json`	Package configuration with dual Koa version support
`packages/koa/deno.json`	Deno configuration for JSR distribution
`packages/koa/README.md`	Package documentation with basic usage example
`examples/koa/`	Complete example application demonstrating Koa integration
`docs/manual/integration.md`	Updated documentation with Koa section and installation instructions
`docs/.vitepress/config.mts`	Added Koa reference to documentation navigation
`deno.json`	Added Koa package to Deno workspace

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

packages/koa/src/index.ts

@ts-ignore

- Simplify promise handling for contextData using await - Change @ts-ignore to @ts-expect-error for duplex property - Remove unnecessary parentheses around Readable.toWeb() - Remove unnecessary Buffer.from() wrapper for stream chunks

github-actions · 2025-10-05T07:16:35Z

The latest push to this pull request has been published to JSR and npm as a pre-release:

Package	Version	JSR	npm
@fedify/fedify	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/cli	1.9.0-pr.455.1742+fb29545a	JSR
@fedify/amqp	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/cfworkers	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/denokv	1.9.0-pr.455.1742+fb29545a	JSR
@fedify/elysia	1.9.0-pr.455.1742+fb29545a		npm
@fedify/express	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/h3	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/hono	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/nestjs	1.9.0-pr.455.1742+fb29545a		npm
@fedify/next	1.9.0-pr.455.1742+fb29545a		npm
@fedify/postgres	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/redis	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/sqlite	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/sveltekit	1.9.0-pr.455.1742+fb29545a	JSR	npm
@fedify/testing	1.9.0-pr.455.1742+fb29545a	JSR	npm

github-actions · 2025-10-05T07:21:54Z

The docs for this pull request have been published:

https://32be115a.fedify.pages.dev

issues-auto-labeler bot added component/integration Web framework integration difficulty/intermediate Intermediate level examples Example code related labels Oct 5, 2025

dahlia added this to STF 2025–2026 Milestone 1: Add Web Framework Integrations Oct 5, 2025

dahlia moved this to In review in STF 2025–2026 Milestone 1: Add Web Framework Integrations Oct 5, 2025

dahlia added this to the Fedify 1.9 milestone Oct 5, 2025

issues-auto-labeler bot added the good first issue Good for newcomers label Oct 5, 2025

gemini-code-assist bot reviewed Oct 5, 2025

View reviewed changes

packages/koa/src/index.ts Outdated Show resolved Hide resolved

examples/koa/index.ts Show resolved Hide resolved

dahlia requested a review from Copilot October 5, 2025 06:49

Copilot AI reviewed Oct 5, 2025

View reviewed changes

packages/koa/src/index.ts Outdated Show resolved Hide resolved

packages/koa/src/index.ts Outdated Show resolved Hide resolved

packages/koa/src/index.ts Outdated Show resolved Hide resolved

Apply PR review suggestions

fb29545

- Simplify promise handling for contextData using await - Change @ts-ignore to @ts-expect-error for duplex property - Remove unnecessary parentheses around Readable.toWeb() - Remove unnecessary Buffer.from() wrapper for stream chunks

dahlia temporarily deployed to github-pages October 5, 2025 07:16 — with GitHub Actions Inactive

dahlia merged commit 3b180ef into fedify-dev:main Oct 5, 2025
10 checks passed

github-project-automation bot moved this from In review to Done in STF 2025–2026 Milestone 1: Add Web Framework Integrations Oct 5, 2025

BrewTestBot mentioned this pull request Oct 14, 2025

fedify 1.9.0 Homebrew/homebrew-core#249492

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add Koa framework integration package #455

Add Koa framework integration package #455

Uh oh!

dahlia commented Oct 5, 2025 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Oct 5, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 5, 2025

Uh oh!

github-actions bot commented Oct 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Add Koa framework integration package #455

Add Koa framework integration package #455

Uh oh!

Conversation

dahlia commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Package Implementation (packages/koa/)

Key Features

Example Project (examples/koa/)

Documentation

Configuration Updates

Testing

API Example

Notes

Uh oh!

gemini-code-assist bot commented Oct 5, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 5, 2025

Uh oh!

github-actions bot commented Oct 5, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dahlia commented Oct 5, 2025 •

edited

Loading

Package Implementation (`packages/koa/`)

Example Project (`examples/koa/`)