name	azure-functions-v4-migration
description	Guides migration of Azure Functions apps from deprecated v3 model (Express-based, per-function index.ts + function.json) to the v4 programming model using wrapHandlerV4 from @pagopa/io-functions-commons. Covers HTTP triggers, Durable Functions (orchestrators + activities), Queue triggers, CosmosDB change feed triggers, Blob triggers, and handler-kit queue functions. Use when asked to upgrade Azure Functions, migrate from v3 to v4, replace wrapRequestHandler with wrapHandlerV4, remove function.json and index.ts per-function files, or create a single main.ts entry point.
license	Complete terms in LICENSE.txt

Azure Functions v4 Migration Skill

This skill guides the migration of Azure Function apps in this monorepo from the deprecated v3 model (Express-based, per-function index.ts + function.json) to the v4 programming model using wrapHandlerV4 from @pagopa/io-functions-commons. It covers all trigger types found in this project: HTTP, Durable Functions (orchestrators + activities), Queue, CosmosDB change feed, Blob, and handler-kit functions.

When to Use This Skill

Migrating an Azure Functions app from v3 to v4 programming model
Replacing wrapRequestHandler / withRequestMiddlewares with wrapHandlerV4
Converting per-function function.json + index.ts files to a single src/main.ts entry point
Upgrading @azure/functions from ^3.x to ^4.x
Upgrading durable-functions from ^1.x to ^3.x
Replacing Context (v3) with InvocationContext (v4)
Replacing IOrchestrationFunctionContext with OrchestrationContext (durable-functions v3)
Replacing df.orchestrator() wrappers with df.app.orchestration() registrations
Migrating activity triggers from function.json to df.app.activity() registrations
Migrating queue triggers from function.json to app.storageQueue() registrations
Migrating CosmosDB change feed triggers from function.json to app.cosmosDB() registrations
Migrating blob triggers from function.json to app.storageBlob() registrations
Upgrading @pagopa/handler-kit / @pagopa/handler-kit-azure-func for queue functions
Replacing Express-style custom middlewares with @pagopa/io-functions-commons built-in middlewares

Prerequisites

@azure/functions upgraded to ^4.0.0 (moved from devDependencies to dependencies)
@pagopa/io-functions-commons at ^30.0.0 or later (provides wrapHandlerV4)
durable-functions upgraded to ^3.0.0 (if Durable Functions are used)
@pagopa/handler-kit upgraded to ^1.1.1 and @pagopa/handler-kit-azure-func upgraded to ^2.0.8 (if handler-kit queue functions are used)
express, @pagopa/express-azure-functions, winston, winston-transport removed from dependencies

Step-by-Step Workflow

For detailed code examples and before/after patterns see migration-guide.md.

1. Update `package.json`

See package.json changes.

2. Update each HTTP `handler.ts`

See handler.ts changes.

3. Create `src/main.ts`

See main.ts creation and use the main.ts template as a starting point.

Verification Steps

Run these checks at the end of every migration iteration (repeat for up to 5 iterations until all pass without errors).

Step A — Build

yarn workspace io-functions-admin build

Confirm that tsc emits to dist/ with no errors and the dependency-check post-build step passes.

Step B — Lint (with auto-fix)

yarn workspace io-functions-admin lint

ESLint runs with auto-fix enabled. If fixes are applied, review the changes. Re-run until no errors are reported.

Step C — Tests

yarn workspace io-functions-admin test

All vitest test suites must pass. If tests fail after migration, check that:

Handler imports reference the updated handler.ts exports (not old index.ts).
Mocked types use InvocationContext instead of Context (v3).
Orchestrator handlers use OrchestrationContext instead of IOrchestrationFunctionContext.

Iteration policy

Run steps A → B → C in order after every batch of changes.
If any step fails, fix the reported errors before proceeding to the next function.
Stop after 5 iterations; if issues persist, surface them to the developer for manual review.
All three steps must be green before the migration of a function is considered complete.

References

name	azure-functions-v4-migration
description	Guides migration of Azure Functions apps from deprecated v3 model (Express-based, per-function index.ts + function.json) to the v4 programming model using wrapHandlerV4 from @pagopa/io-functions-commons. Covers HTTP triggers, Durable Functions (orchestrators + activities), Queue triggers, CosmosDB change feed triggers, Blob triggers, and handler-kit queue functions. Use when asked to upgrade Azure Functions, migrate from v3 to v4, replace wrapRequestHandler with wrapHandlerV4, remove function.json and index.ts per-function files, or create a single main.ts entry point.
license	Complete terms in LICENSE.txt