feat: add @aixyz/next — zero-config Next.js App Router adapter for AixyzApp

[Copilot]

Adds a new @aixyz/next package that wires AixyzApp into Next.js App Router Route Handlers. Because AixyzApp.fetch already speaks web-standard Request/Response, no request/response conversion is needed.

New package: packages/aixyz-next

Zero-config API: withAixyzConfig(nextConfig) ✨

The primary entry point. Add it to next.config.ts — that's the only change needed. withAixyzConfig auto-scans ./app/agent.ts and ./app/tools/*.ts, wires up all plugins (A2APlugin, MCPPlugin, IndexPagePlugin) and the default x402 facilitator automatically, and generates the route handler on each build. On first run it also auto-creates app/api/[[...route]]/route.ts with a single stable re-export line (safe to commit).

// next.config.ts
import { withAixyzConfig } from "@aixyz/next";
export default withAixyzConfig({});

That's it — no route file imports, no plugin wiring, nothing else. The auto-created app/api/[[...route]]/route.ts looks like this:

// Auto-generated by @aixyz/next — safe to commit
export { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } from "@aixyz/next/route";

How it works internally:

• Inside the webpack function, options.dir (the real Next.js project root) is used to scan ./app/agent.ts and ./app/tools/*.ts
• A handler module is generated into .next/cache/aixyz/route.mjs with all discovered imports wired into createNextHandler
• A webpack alias redirects @aixyz/next/route to that generated file
• Files starting with _ in tools/ are excluded (mirrors the CLI convention)

Mid-level API: createNextHandler(options)

For cases where you want to pass agent/tool modules explicitly rather than relying on filesystem scanning.

// app/api/[[...route]]/route.ts
import { createNextHandler } from "@aixyz/next";
import * as agent from "../../agent";
import * as weatherTool from "../../tools/weather";

export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } = createNextHandler({
  agent,
  tools: [{ name: "weather", exports: weatherTool }],
});

Plugins are wired up automatically and the app lazy-initializes on the first request (cold-start friendly for Next.js serverless functions).

Low-level API: toNextRouteHandler(app)

Escape-hatch for users who need full manual control over the AixyzApp setup (custom plugins, custom facilitators, etc.).

// app/api/[[...route]]/route.ts
import { toNextRouteHandler } from "@aixyz/next";
import { AixyzApp } from "aixyz/app";
import { A2APlugin } from "aixyz/app/plugins/a2a";
import * as agent from "../../agent";

const app = new AixyzApp();
await app.withPlugin(new A2APlugin(agent));
await app.initialize();

export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } = toNextRouteHandler(app);

@aixyz/next/route placeholder

route.ts is a TypeScript placeholder that provides editor types for import from "@aixyz/next/route". At build time it is replaced by the webpack alias set up by withAixyzConfig. Without withAixyzConfig it throws a helpful error pointing to the docs.

Package details

• Peer deps: aixyz (workspace), next >=14, ai ^6 (optional)
• @aixyz/config added to devDependencies so mock.module resolves correctly across workspace boundaries in tests
• x402 is conditionally enabled — only when a real facilitator is available
• ./route added to package exports map
• 27 tests covering withAixyzConfig, ensureRouteFile, generateAixyzRoute, createNextHandler, and toNextRouteHandler

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[linear]

XYZ-83 `@aixyz/next` so since we support WebStandard Fetch, let's write an adapter such that we support NextJs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-boilerplate	Error		Mar 14, 2026 11:27am
agent-chainlink	Error		Mar 14, 2026 11:27am
agent-job-hunter	Ready	Preview, Comment	Mar 14, 2026 11:27am
agent-price-oracle	Ready	Preview, Comment	Mar 14, 2026 11:27am
agent-travel	Error		Mar 14, 2026 11:27am
agent-with-custom-server	Error		Mar 14, 2026 11:27am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
ai-xyz.dev	Ignored		Mar 14, 2026 11:27am

[fuxingloh]

@copilot this is not magical enough. Can you improve the implementation.

[Copilot]

@copilot this is not magical enough. Can you improve the implementation.

Updated in 89aa4c0. The package now exposes a high-level createNextHandler(options) that auto-wires everything — just pass your agent and tool module exports:

// app/api/[[...route]]/route.ts
import { createNextHandler } from "@aixyz/next";
import * as agent from "../../agent";
import * as weatherTool from "../../tools/weather";

export const { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS } = createNextHandler({
  agent,
  tools: [{ name: "weather", exports: weatherTool }],
});

Internally it auto-creates AixyzApp, wires up A2APlugin, MCPPlugin, IndexPagePlugin, and the default x402 facilitator — mirroring exactly what the CLI's generateServer does. The app lazy-initializes on the first request (cold-start friendly). toNextRouteHandler(app) is kept as the low-level escape-hatch for full control.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• mainnet.base.org
  • Triggering command: /usr/local/bin/node node dist/cli.js dev --anvil-port 8545 --anvil-host 0.0.0.0 --port 4022 --rpc-url REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[fuxingloh]

@copilot

It should be as simple as this:

./app/tools and ./app/agent.ts auto building

withAixyzConfig(nextConfig)

[Copilot]

@copilot

It should be as simple as this:
...

Done in 402b4b3. The only thing needed in a Next.js project is now:

// next.config.ts
import { withAixyzConfig } from "@aixyz/next";
export default withAixyzConfig({});

withAixyzConfig auto-scans ./app/agent.ts and ./app/tools/*.ts, generates .next/cache/aixyz/route.mjs with all plugins wired up, and auto-creates app/api/[[...route]]/route.ts on first run (a single stable re-export line, safe to commit). No manual imports needed anywhere.