feat(utils): define file config (#13283)

** What
 - Allow auto-loaded Medusa files to export a config object.
 - Currently supports isDisabled to control loading.
 - new instance `FeatureFlag` exported by `@medusajs/framework/utils`
 - `feature-flags` is now a supported folder for medusa projects, modules, providers and plugins. They will be loaded and added to `FeatureFlag`

** Why
 - Enables conditional loading of routes, migrations, jobs, subscribers, workflows, and other files based on feature flags.

```ts
// /src/feature-flags

import { FlagSettings } from "@medusajs/framework/feature-flags"

const CustomFeatureFlag: FlagSettings = {
  key: "custom_feature",
  default_val: false,
  env_key: "FF_MY_CUSTOM_FEATURE",
  description: "Enable xyz",
}

export default CustomFeatureFlag
```

```ts
// /src/modules/my-custom-module/migration/Migration20250822135845.ts

import { FeatureFlag } from "@medusajs/framework/utils"

export class Migration20250822135845 extends Migration {
  override async up(){ }
  override async down(){ }
}

defineFileConfig({
  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_feature")
})
```

integration-tests/http/__fixtures__/feature-flag/medusa-config.ts

@@ -0,0 +1,26 @@
+const { defineConfig } = require("@medusajs/framework/utils")
+
+const DB_HOST = process.env.DB_HOST
+const DB_USERNAME = process.env.DB_USERNAME
+const DB_PASSWORD = process.env.DB_PASSWORD
+const DB_NAME = process.env.DB_TEMP_NAME
+const DB_URL = `postgres://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}/${DB_NAME}`
+
+process.env.DATABASE_URL = DB_URL
+
+module.exports = defineConfig({
+  admin: {
+    disable: true,
+  },
+  projectConfig: {
+    http: {
+      jwtSecret: "secret",
+    },
+  },
+  modules: [
+    {
+      key: "custom",
+      resolve: "src/modules/custom",
+    },
+  ],
+})

integration-tests/http/__fixtures__/feature-flag/src/api/custom/route.ts

@@ -0,0 +1,10 @@
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { defineFileConfig, FeatureFlag } from "@medusajs/utils"
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})
+
+export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
+  res.json({ message: "Custom GET" })
+}

integration-tests/http/__fixtures__/feature-flag/src/feature-flags/custom-ff.ts

@@ -0,0 +1,8 @@
+import { FlagSettings } from "@medusajs/framework/feature-flags"
+
+export const CustomFeatureFlag: FlagSettings = {
+  key: "custom_ff",
+  default_val: false,
+  env_key: "CUSTOM_FF",
+  description: "Custom feature flag",
+}

integration-tests/http/__fixtures__/feature-flag/src/jobs/test-job.ts

@@ -0,0 +1,18 @@
+import { MedusaContainer } from "@medusajs/framework/types"
+import { defineFileConfig, FeatureFlag } from "@medusajs/framework/utils"
+
+export const testJobHandler = jest.fn()
+
+export default async function greetingJob(container: MedusaContainer) {
+  testJobHandler()
+}
+
+export const config = {
+  name: "greeting-every-second",
+  numberOfExecutions: 1,
+  schedule: "* * * * * *",
+}
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})

integration-tests/http/__fixtures__/feature-flag/src/modules/custom/index.ts

@@ -0,0 +1,8 @@
+import { ModuleExports } from "@medusajs/types"
+import { ModuleService } from "./services/module-service"
+
+const moduleExports: ModuleExports = {
+  service: ModuleService,
+}
+
+export default moduleExports

integration-tests/http/__fixtures__/feature-flag/src/modules/custom/migrations/MigrationTest.ts

@@ -0,0 +1,12 @@
+import { FeatureFlag, defineFileConfig } from "@medusajs/framework/utils"
+import { Migration } from "@mikro-orm/migrations"
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})
+
+export class MigrationTest extends Migration {
+  override async up(): Promise<void> {}
+
+  override async down(): Promise<void> {}
+}

integration-tests/http/__fixtures__/feature-flag/src/modules/custom/services/module-service.ts

@@ -0,0 +1,12 @@
+import { IModuleService } from "@medusajs/types"
+import { MedusaContext } from "@medusajs/utils"
+
+// @ts-expect-error
+export class ModuleService implements IModuleService {
+  public property = "value"
+
+  constructor() {}
+  async methodName(input, @MedusaContext() context) {
+    return input + " called"
+  }
+}

integration-tests/http/__fixtures__/feature-flag/src/subscribers/test-event-payload.ts

@@ -0,0 +1,13 @@
+import { defineFileConfig, FeatureFlag } from "@medusajs/framework/utils"
+
+const testProductCreatedHandlerMock = jest.fn()
+
+export default testProductCreatedHandlerMock
+
+export const config = {
+  event: "event.test",
+}
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})

integration-tests/http/__fixtures__/feature-flag/src/workflows/test-workflow.ts

@@ -0,0 +1,14 @@
+import { defineFileConfig, FeatureFlag } from "@medusajs/framework/utils"
+import { createStep, createWorkflow } from "@medusajs/framework/workflows-sdk"
+
+const testWorkflowHandler = jest.fn()
+
+const step1 = createStep("step1", () => testWorkflowHandler())
+
+export const testWorkflow = createWorkflow("test-workflow", () => {
+  step1()
+})
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})

integration-tests/http/__tests__/auth/admin/auth-asymetric.spec.ts

@@ -1,12 +1,12 @@
 import { generateResetPasswordTokenWorkflow } from "@medusajs/core-flows"
 import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { ContainerRegistrationKeys } from "@medusajs/utils"
 import jwt from "jsonwebtoken"
+import path from "path"
 import {
   adminHeaders,
   createAdminUser,
 } from "../../../../helpers/create-admin-user"
-import path from "path"
-import { ContainerRegistrationKeys } from "@medusajs/utils"
 
 jest.setTimeout(100000)
 

integration-tests/http/__tests__/campaigns/admin/campaigns.spec.ts

@@ -76,7 +76,7 @@ const promotionData = {
   ],
 }
 
-const env = { MEDUSA_FF_MEDUSA_V2: true }
+const env = {}
 const adminHeaders = {
   headers: { "x-medusa-access-token": "test_token" },
 }

integration-tests/http/__tests__/cart/store/cart.spec.ts

@@ -20,7 +20,7 @@ import { medusaTshirtProduct } from "../../../__fixtures__/product"
 
 jest.setTimeout(100000)
 
-const env = { MEDUSA_FF_MEDUSA_V2: true }
+const env = {}
 const adminHeaders = { headers: { "x-medusa-access-token": "test_token" } }
 
 const shippingAddressData = {

integration-tests/http/__tests__/feature-flag/resources-with-flags.spec.ts

@@ -0,0 +1,49 @@
+import { MedusaWorkflow } from "@medusajs/framework/workflows-sdk"
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import path from "path"
+import { setTimeout as setTimeoutPromise } from "timers/promises"
+import { testJobHandler } from "../../__fixtures__/feature-flag/src/jobs/test-job"
+
+jest.setTimeout(100000)
+
+medusaIntegrationTestRunner({
+  cwd: path.join(__dirname, "../../__fixtures__/feature-flag"),
+  env: {
+    CUSTOM_FF: true,
+  },
+  testSuite: ({ api, dbConnection }) => {
+    describe("Resources loaded with feature flags", () => {
+      it("should load migration when feature flag is enabled and run job", async () => {
+        const migrationNotExecuted = await dbConnection.raw(
+          `SELECT name FROM "mikro_orm_migrations" WHERE name = 'Noop'`
+        )
+        expect(migrationNotExecuted.rows).toHaveLength(0)
+
+        const migrationExecuted = await dbConnection.raw(
+          `SELECT name FROM "mikro_orm_migrations" WHERE name = 'MigrationTest'`
+        )
+
+        expect(migrationExecuted.rows).toHaveLength(1)
+        expect(migrationExecuted.rows[0].name).toBe("MigrationTest")
+
+        await setTimeoutPromise(1000)
+
+        expect(testJobHandler).toHaveBeenCalledTimes(1)
+      })
+
+      it("should load workflow when feature flag is enabled", async () => {
+        expect(MedusaWorkflow.getWorkflow("test-workflow")).toBeDefined()
+      })
+
+      it("should load scheduled job when feature flag is enabled", async () => {
+        expect(
+          MedusaWorkflow.getWorkflow("job-greeting-every-second")
+        ).toBeDefined()
+      })
+
+      it("should load endpoint when feature flag is enabled", async () => {
+        expect((await api.get("/custom")).status).toBe(200)
+      })
+    })
+  },
+})

integration-tests/http/__tests__/feature-flag/resources-without-flags.spec.ts

@@ -0,0 +1,46 @@
+import { MedusaWorkflow } from "@medusajs/framework/workflows-sdk"
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import path from "path"
+import { setTimeout as setTimeoutPromise } from "timers/promises"
+import { testJobHandler } from "../../__fixtures__/feature-flag/src/jobs/test-job"
+
+jest.setTimeout(100000)
+
+medusaIntegrationTestRunner({
+  cwd: path.join(__dirname, "../../__fixtures__/feature-flag"),
+  testSuite: ({ api, dbConnection }) => {
+    describe("Resources loaded without feature flags", () => {
+      it("should not load migration when feature flag is disabled and not run job", async () => {
+        const migrationNotExecuted = await dbConnection.raw(
+          `SELECT name FROM "mikro_orm_migrations" WHERE name = 'MigrationTest'`
+        )
+        expect(migrationNotExecuted.rows).toHaveLength(0)
+
+        const migrationExecuted = await dbConnection.raw(
+          `SELECT name FROM "mikro_orm_migrations" WHERE name = 'Noop'`
+        )
+
+        expect(migrationExecuted.rows).toHaveLength(1)
+        expect(migrationExecuted.rows[0].name).toBe("Noop")
+
+        await setTimeoutPromise(1000)
+
+        expect(testJobHandler).toHaveBeenCalledTimes(0)
+      })
+
+      it("should not load workflow when feature flag is disabled", async () => {
+        expect(MedusaWorkflow.getWorkflow("test-workflow")).toBeUndefined()
+      })
+
+      it("should not load scheduled job when feature flag is disabled", async () => {
+        expect(
+          MedusaWorkflow.getWorkflow("job-greeting-every-second")
+        ).toBeUndefined()
+      })
+
+      it("should not load endpoint when feature flag is disabled", async () => {
+        expect(api.get("/custom")).rejects.toThrow()
+      })
+    })
+  },
+})

integration-tests/http/__tests__/shipping-option/store/shipping-option-calculated.spec.ts

@@ -7,7 +7,7 @@ import {
 
 jest.setTimeout(50000)
 
-const env = { MEDUSA_FF_MEDUSA_V2: true }
+const env = {}
 const adminHeaders = { headers: { "x-medusa-access-token": "test_token" } }
 
 medusaIntegrationTestRunner({

integration-tests/http/__tests__/shipping-option/store/shipping-option.spec.ts

@@ -7,7 +7,7 @@ import {
 
 jest.setTimeout(50000)
 
-const env = { MEDUSA_FF_MEDUSA_V2: true }
+const env = {}
 const adminHeaders = { headers: { "x-medusa-access-token": "test_token" } }
 
 medusaIntegrationTestRunner({

integration-tests/http/__tests__/tax-region/admin/tax-region.spec.ts

@@ -3,7 +3,7 @@ import { createAdminUser } from "../../../../helpers/create-admin-user"
 
 jest.setTimeout(50000)
 
-const env = { MEDUSA_FF_MEDUSA_V2: true }
+const env = {}
 const adminHeaders = {
   headers: { "x-medusa-access-token": "test_token" },
 }

integration-tests/http/__tests__/view-configurations.spec.ts

@@ -1,10 +1,9 @@
 import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
 import { adminHeaders, createAdminUser } from "../../helpers/create-admin-user"
-import { Modules, ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
 jest.setTimeout(50000)
 
-const env = { MEDUSA_FF_MEDUSA_V2: true, MEDUSA_FF_VIEW_CONFIGURATIONS: true }
+const env = { MEDUSA_FF_VIEW_CONFIGURATIONS: true }
 
 medusaIntegrationTestRunner({
   env,