feat: Simplify driver version migration through magento-version file

apps/demo/src/app/drivers/magento-version.ts

@@ -0,0 +1,4 @@
+// To use a different Magento API version, change the import paths below.
+// Supported versions: 2.4.1, 2.4.2, 2.4.3
+export { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+export { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';

apps/demo/src/app/drivers/magento.providers.ts

@@ -11,13 +11,13 @@ import {
   provideMagentoDriver,
   withOperationCache,
 } from '@daffodil/driver/magento';
-import { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
 import { DaffGeographyMagentoDriverModule } from '@daffodil/geography/driver/magento';
 import { DaffNavigationMagentoDriverModule } from '@daffodil/navigation/driver/magento';
 import { DaffNewsletterTestingDriverModule } from '@daffodil/newsletter/driver/testing';
 import { DaffProductMagentoDriverModule } from '@daffodil/product/driver/magento';
 
 import { possibleTypes } from './magento/fragmentTypes.json';
+import { provideDaffExternalRouterMagentoDriver } from './magento-version';
 import { environment } from '../../environments/environment';
 import { MagentoEnvironmentDriverConfiguration } from '../../environments/environment.interface';
 

libs/external-router/driver/magento/2.4.1/src/magento.module.ts

@@ -12,6 +12,8 @@ import { DaffExternalRouterMagentoDriver } from './magento.service';
 /**
  * The module used to configure the {@link DaffExternalRouterDriver} for usage with Magento.
  *
+ * @deprecated Use `provideDaffExternalRouterMagentoDriver` instead.
+ *
  * @example
  * ```ts
  * @NgModule({
@@ -34,6 +36,8 @@ export class DaffExternalRouterDriverMagentoModule {
 
   /**
    * Configures the package for the root injector.
+   *
+   * @deprecated Use `provideDaffExternalRouterMagentoDriver` instead.
    */
   static forRoot(): ModuleWithProviders<DaffExternalRouterDriverMagentoModule> {
     return {

libs/external-router/driver/magento/2.4.1/src/provider.spec.ts

@@ -0,0 +1,20 @@
+import { TestBed } from '@angular/core/testing';
+import { ApolloTestingModule } from 'apollo-angular/testing';
+
+import { DaffExternalRouterDriver } from '@daffodil/external-router/driver';
+import { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.1';
+
+describe('@daffodil/external-router/driver/magento/2.4.1 | provideDaffExternalRouterMagentoDriver', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [ApolloTestingModule],
+      providers: [
+        provideDaffExternalRouterMagentoDriver(),
+      ],
+    });
+  });
+
+  it('should allow you to inject the driver', () => {
+    expect(TestBed.inject(DaffExternalRouterDriver)).toBeTruthy();
+  });
+});

libs/external-router/driver/magento/2.4.1/src/provider.ts

@@ -0,0 +1,19 @@
+import {
+  EnvironmentProviders,
+  makeEnvironmentProviders,
+} from '@angular/core';
+
+import { provideDaffMagentoCacheableOperation } from '@daffodil/driver/magento';
+import { provideDaffExternalRouterDriver } from '@daffodil/external-router/driver';
+
+import { DAFF_MAGENTO_RESOLVE_URL_QUERY_NAME } from './graphql/queries/resolve-url-v2.4.1';
+import { DaffExternalRouterMagentoDriver } from './magento.service';
+
+/**
+ * Provides a Magento 2.4.1 implementation of {@link DaffExternalRouterDriver}.
+ */
+export const provideDaffExternalRouterMagentoDriver = (
+): EnvironmentProviders => makeEnvironmentProviders([
+  provideDaffExternalRouterDriver(DaffExternalRouterMagentoDriver),
+  provideDaffMagentoCacheableOperation(DAFF_MAGENTO_RESOLVE_URL_QUERY_NAME),
+]);

libs/external-router/driver/magento/2.4.1/src/public_api.ts

@@ -4,3 +4,4 @@
 
 export { DaffExternalRouterMagentoDriver } from './magento.service';
 export { DaffExternalRouterDriverMagentoModule } from './magento.module';
+export { provideDaffExternalRouterMagentoDriver } from './provider';

libs/external-router/driver/magento/2.4.2/src/magento.module.ts

@@ -13,6 +13,8 @@ import { DaffExternalRouterMagentoDriver } from './magento.service';
 /**
  * The module used to configure the {@link DaffExternalRouterDriver} for usage with Magento.
  *
+ * @deprecated Use `provideDaffExternalRouterMagentoDriver` instead.
+ *
  * @example
  * ```ts
  * @NgModule({
@@ -35,6 +37,8 @@ export class DaffExternalRouterDriverMagentoModule {
 
   /**
    * Configures the package for the root injector.
+   *
+   * @deprecated Use `provideDaffExternalRouterMagentoDriver` instead.
    */
   static forRoot(): ModuleWithProviders<DaffExternalRouterDriverMagentoModule> {
     return {

libs/external-router/driver/magento/2.4.2/src/provider.spec.ts

@@ -0,0 +1,20 @@
+import { TestBed } from '@angular/core/testing';
+import { ApolloTestingModule } from 'apollo-angular/testing';
+
+import { DaffExternalRouterDriver } from '@daffodil/external-router/driver';
+import { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.2';
+
+describe('@daffodil/external-router/driver/magento/2.4.2 | provideDaffExternalRouterMagentoDriver', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [ApolloTestingModule],
+      providers: [
+        provideDaffExternalRouterMagentoDriver(),
+      ],
+    });
+  });
+
+  it('should allow you to inject the driver', () => {
+    expect(TestBed.inject(DaffExternalRouterDriver)).toBeTruthy();
+  });
+});

libs/external-router/driver/magento/2.4.2/src/provider.ts

@@ -0,0 +1,19 @@
+import {
+  EnvironmentProviders,
+  makeEnvironmentProviders,
+} from '@angular/core';
+
+import { provideDaffMagentoCacheableOperation } from '@daffodil/driver/magento';
+import { provideDaffExternalRouterDriver } from '@daffodil/external-router/driver';
+
+import { DAFF_MAGENTO_RESOLVE_URL_QUERY_NAME } from './graphql/queries/resolve-url-v2.4.2';
+import { DaffExternalRouterMagentoDriver } from './magento.service';
+
+/**
+ * Provides a Magento 2.4.2 implementation of {@link DaffExternalRouterDriver}.
+ */
+export const provideDaffExternalRouterMagentoDriver = (
+): EnvironmentProviders => makeEnvironmentProviders([
+  provideDaffExternalRouterDriver(DaffExternalRouterMagentoDriver),
+  provideDaffMagentoCacheableOperation(DAFF_MAGENTO_RESOLVE_URL_QUERY_NAME),
+]);

libs/external-router/driver/magento/2.4.2/src/public_api.ts

@@ -4,3 +4,4 @@
 
 export { DaffExternalRouterMagentoDriver } from './magento.service';
 export { DaffExternalRouterDriverMagentoModule } from './magento.module';
+export { provideDaffExternalRouterMagentoDriver } from './provider';

libs/external-router/driver/magento/2.4.3/src/magento.module.ts

@@ -13,6 +13,8 @@ import { DaffExternalRouterMagentoDriver } from './magento.service';
 /**
  * The module used to configure the {@link DaffExternalRouterDriver} for usage with Magento.
  *
+ * @deprecated Use `provideDaffExternalRouterMagentoDriver` instead.
+ *
  * @example
  * ```ts
  * @NgModule({
@@ -35,6 +37,8 @@ export class DaffExternalRouterDriverMagentoModule {
 
   /**
    * Configures the package for the root injector.
+   *
+   * @deprecated Use `provideDaffExternalRouterMagentoDriver` instead.
    */
   static forRoot(): ModuleWithProviders<DaffExternalRouterDriverMagentoModule> {
     return {

libs/external-router/guides/drivers/magento.md

@@ -10,29 +10,42 @@ npm install @daffodil/external-router --save
 
 ## Getting started
 
-To use the Magento drivers, you need to import and configure the appropriate modules and services in your Angular application.
+To use the Magento drivers, you need to import and configure the appropriate providers and services in your Angular application.
 
 Magento's GraphQl API has changed with its various versions, with the most recent versions of Magento supporting the `routes` GraphQl query.
 
 As such, most recent versions of Magento should use the driver version which first introduced support for this: `DaffExternalRouterDriverMagentoModule` from `@daffodil/external-router/driver/magento/2.4.3`.
 
-| Magento Version | Module                                   | Package                                          | SEO Data Support |
-| --------------- | ---------------------------------------- | ------------------------------------------------ | ---------------- |
-| v2.4.1          | `DaffExternalRouterDriverMagentoModule`  | `@daffodil/external-router/driver/magento/2.4.1` | No               |
-| v2.4.2          | `DaffExternalRouterDriverMagentoModule`  | `@daffodil/external-router/driver/magento/2.4.2` | No               |
-| v2.4.3+         | `provideDaffExternalRouterMagentoDriver` | `@daffodil/external-router/driver/magento/2.4.3` | Yes              |
+| Magento Version | Provider                                   | Package                                          | SEO Data Support |
+| --------------- | ------------------------------------------ | ------------------------------------------------ | ---------------- |
+| v2.4.1          | `provideDaffExternalRouterMagentoDriver`   | `@daffodil/external-router/driver/magento/2.4.1` | No               |
+| v2.4.2          | `provideDaffExternalRouterMagentoDriver`   | `@daffodil/external-router/driver/magento/2.4.2` | No               |
+| v2.4.3+         | `provideDaffExternalRouterMagentoDriver`   | `@daffodil/external-router/driver/magento/2.4.3` | Yes              |
 
-## Usage
+## Selecting a driver version
 
-To use the Magento driver for external router with the latest version of Magento:
+Each version is a separate package entry point. Only the version you import ends up in your production bundle — unused versions are never included.
+
+The recommended pattern is to create a single `magento-version.ts` file in your app that re-exports from the correct version entry point. All other app files import from this stub, so the version is declared in exactly one place.
+
+```ts
+// src/app/drivers/magento-version.ts
+// To use a different Magento API version, change the import paths below.
+// Supported versions: 2.4.1, 2.4.2, 2.4.3
+export { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+export { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+```
+
+Your providers file then imports from the stub:
 
 ```ts
+// src/app/app.config.ts
 import { ApplicationConfig } from '@angular/core';
 import { provideClientHydration } from '@angular/platform-browser';
 import { provideRouter } from '@angular/router';
 
 import { provideExternalRouter } from '@daffodil/external-router';
-import { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+import { provideDaffExternalRouterMagentoDriver } from './drivers/magento-version';
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -43,3 +56,52 @@ export const appConfig: ApplicationConfig = {
   ],
 };
 ```
+
+## Upgrading Magento version
+
+When you upgrade your Magento store to a new version, update the two import paths in `magento-version.ts`:
+
+```diff
+- export { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.2';
+- export { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.2';
++ export { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
++ export { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+```
+
+No other app code needs to change. Only the new version's bundle will be included in your build.
+
+## Upgrading daffodil without upgrading Magento
+
+No changes are needed. Your `magento-version.ts` stub already points to your Magento version's entry point, which continues to work across daffodil upgrades. Old version entry points remain available until they are removed in a future major daffodil release (with a deprecation notice ahead of time).
+
+## Migrating from NgModule
+
+If your app uses the deprecated `DaffExternalRouterDriverMagentoModule`, migrate to the provider function:
+
+**Before:**
+
+```ts
+@NgModule({
+  imports: [
+    DaffExternalRouterDriverMagentoModule.forRoot()
+  ]
+})
+export class AppModule {}
+```
+
+**After:**
+
+```ts
+// src/app/drivers/magento-version.ts
+export { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+export { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
+```
+
+```ts
+// src/app/app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideDaffExternalRouterMagentoDriver(),
+  ],
+};
+```

tools/schematics/ng-add/files/app/daff/external-router/drivers/dynamic.ts

@@ -20,10 +20,10 @@ import {
 import { DaffExternallyResolvableUrl } from '@daffodil/external-router';
 import { DaffExternalRouterDriverInterface } from '@daffodil/external-router/driver';
 import { DaffExternalRouterInMemoryDriver } from '@daffodil/external-router/driver/in-memory';
-import { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3';
 import { DaffShopifyExternalRouterDriver } from '@daffodil/external-router/driver/shopify';
 
 import { FakeExternalRouterService } from './fake';
+import { DaffExternalRouterMagentoDriver } from '../../../drivers/magento-version';
 
 @Injectable({
   providedIn:'root',

tools/schematics/ng-add/generators/providers/drivers/magento.spec.ts

@@ -50,4 +50,20 @@ export class App {}
     expect(appConfigContent).toContain('provideDaffNavigationMagentoDriver');
     expect(appConfigContent).toContain('provideDaffExternalRouterMagentoDriver');
   });
+
+  it('should generate the magento-version stub defaulting to 2.4.3', () => {
+    const rule = addCoreProvidersToStandalone(options, project);
+    const resultTree = <Tree>rule(tree, <any>{});
+    const stubContent = resultTree.read('/projects/test-app/src/app/drivers/magento-version.ts')?.toString();
+
+    expect(stubContent).toContain('@daffodil/external-router/driver/magento/2.4.3');
+  });
+
+  it('should generate the magento-version stub for the specified magentoVersion', () => {
+    const rule = addCoreProvidersToStandalone({ ...options, magentoVersion: '2.4.1' }, project);
+    const resultTree = <Tree>rule(tree, <any>{});
+    const stubContent = resultTree.read('/projects/test-app/src/app/drivers/magento-version.ts')?.toString();
+
+    expect(stubContent).toContain('@daffodil/external-router/driver/magento/2.4.1');
+  });
 });

tools/schematics/ng-add/generators/providers/standalone.ts

@@ -8,6 +8,21 @@ import { NgAddOptions } from '../../schema';
 
 export const addCoreProvidersToStandalone = (options: NgAddOptions, project: any): Rule => (tree: Tree) => {
   const driver = options.driver || 'demo';
+  const magentoVersion = options.magentoVersion || '2.4.3';
+
+  if (driver === 'magento' || driver === 'demo') {
+    const stubPath = `${project.sourceRoot}/app/drivers/magento-version.ts`;
+    const stubContent = `// To use a different Magento API version, change the import paths below.
+// Supported versions: 2.4.1, 2.4.2, 2.4.3
+export { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/${magentoVersion}';
+export { DaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/${magentoVersion}';
+`;
+    if (tree.exists(stubPath)) {
+      tree.overwrite(stubPath, stubContent);
+    } else {
+      tree.create(stubPath, stubContent);
+    }
+  }
 
   const coreProviders = [
     'provideHttpClient()',

tools/schematics/ng-add/schema.json

@@ -53,6 +53,16 @@
           }
         ]
       }
+    },
+    "magentoVersion": {
+      "type": "string",
+      "description": "Which version of the Magento API does your store use? Only applies when driver is 'magento'. Supported values: 2.4.1, 2.4.2, 2.4.3",
+      "enum": [
+        "2.4.1",
+        "2.4.2",
+        "2.4.3"
+      ],
+      "default": "2.4.3"
     }
   }
 }

tools/schematics/ng-add/schema.ts

@@ -3,4 +3,5 @@ export interface NgAddOptions {
   skipPackageJson?: boolean;
   isNewProject?: boolean;
   driver?: 'magento' | 'shopify' | 'in-memory' | 'demo';
+  magentoVersion?: '2.4.1' | '2.4.2' | '2.4.3';
 }

tools/schematics/utils/module-utils.ts

@@ -230,8 +230,8 @@ function getPackageForProvider(providerName: string): string {
     provideDaffNavigationDriver: '@daffodil/navigation/driver',
     provideExternalRouter: '@daffodil/external-router',
     provideDaffExternalRouterInMemoryDriver: '@daffodil/external-router/driver/in-memory',
-    provideDaffExternalRouterMagentoDriver: '@daffodil/external-router/driver/magento/2.4.3',
-    DaffExternalRouterMagentoDriver: '@daffodil/external-router/driver/magento/2.4.3',
+    provideDaffExternalRouterMagentoDriver: './drivers/magento-version',
+    DaffExternalRouterMagentoDriver: './drivers/magento-version',
     provideDaffExternalRouterShopifyDriver: '@daffodil/external-router/driver/shopify',
     DaffExternalRouterShopifyDriver: '@daffodil/external-router/driver/shopify',
     provideDaffExternalRouterDriver: '@daffodil/external-router/driver',