diff --git a/apps/demo/src/app/drivers/magento-version.ts b/apps/demo/src/app/drivers/magento-version.ts new file mode 100644 index 0000000000..8e05337cb7 --- /dev/null +++ b/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'; diff --git a/apps/demo/src/app/drivers/magento.providers.ts b/apps/demo/src/app/drivers/magento.providers.ts index 65234a8112..c8f9eb2f79 100644 --- a/apps/demo/src/app/drivers/magento.providers.ts +++ b/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'; diff --git a/libs/external-router/driver/magento/2.4.1/src/magento.module.ts b/libs/external-router/driver/magento/2.4.1/src/magento.module.ts index 51db157058..cc90555b78 100644 --- a/libs/external-router/driver/magento/2.4.1/src/magento.module.ts +++ b/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 { return { diff --git a/libs/external-router/driver/magento/2.4.1/src/provider.spec.ts b/libs/external-router/driver/magento/2.4.1/src/provider.spec.ts new file mode 100644 index 0000000000..67b2947677 --- /dev/null +++ b/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(); + }); +}); diff --git a/libs/external-router/driver/magento/2.4.1/src/provider.ts b/libs/external-router/driver/magento/2.4.1/src/provider.ts new file mode 100644 index 0000000000..c99f77aeac --- /dev/null +++ b/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), +]); diff --git a/libs/external-router/driver/magento/2.4.1/src/public_api.ts b/libs/external-router/driver/magento/2.4.1/src/public_api.ts index 79cc9ce56e..86b824a122 100644 --- a/libs/external-router/driver/magento/2.4.1/src/public_api.ts +++ b/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'; diff --git a/libs/external-router/driver/magento/2.4.2/src/magento.module.ts b/libs/external-router/driver/magento/2.4.2/src/magento.module.ts index b947e5f049..7ad847c532 100644 --- a/libs/external-router/driver/magento/2.4.2/src/magento.module.ts +++ b/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 { return { diff --git a/libs/external-router/driver/magento/2.4.2/src/provider.spec.ts b/libs/external-router/driver/magento/2.4.2/src/provider.spec.ts new file mode 100644 index 0000000000..689440bd3e --- /dev/null +++ b/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(); + }); +}); diff --git a/libs/external-router/driver/magento/2.4.2/src/provider.ts b/libs/external-router/driver/magento/2.4.2/src/provider.ts new file mode 100644 index 0000000000..327fa1ea96 --- /dev/null +++ b/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), +]); diff --git a/libs/external-router/driver/magento/2.4.2/src/public_api.ts b/libs/external-router/driver/magento/2.4.2/src/public_api.ts index a5987f40e3..0f5e0bd907 100644 --- a/libs/external-router/driver/magento/2.4.2/src/public_api.ts +++ b/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'; diff --git a/libs/external-router/driver/magento/2.4.3/src/magento.module.ts b/libs/external-router/driver/magento/2.4.3/src/magento.module.ts index acc4285d74..90e0a8ff16 100644 --- a/libs/external-router/driver/magento/2.4.3/src/magento.module.ts +++ b/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 { return { diff --git a/libs/external-router/guides/drivers/magento.md b/libs/external-router/guides/drivers/magento.md index 4f8e42db3c..86e3340386 100644 --- a/libs/external-router/guides/drivers/magento.md +++ b/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(), + ], +}; +``` diff --git a/tools/schematics/ng-add/files/app/daff/external-router/drivers/dynamic.ts b/tools/schematics/ng-add/files/app/daff/external-router/drivers/dynamic.ts index 8ddbc6056f..bb982cdc04 100644 --- a/tools/schematics/ng-add/files/app/daff/external-router/drivers/dynamic.ts +++ b/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', diff --git a/tools/schematics/ng-add/generators/providers/drivers/magento.spec.ts b/tools/schematics/ng-add/generators/providers/drivers/magento.spec.ts index 0d65df47af..b20a4577fe 100644 --- a/tools/schematics/ng-add/generators/providers/drivers/magento.spec.ts +++ b/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 = rule(tree, {}); + 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 = rule(tree, {}); + 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'); + }); }); diff --git a/tools/schematics/ng-add/generators/providers/standalone.ts b/tools/schematics/ng-add/generators/providers/standalone.ts index e1dc560557..ca97761fa8 100644 --- a/tools/schematics/ng-add/generators/providers/standalone.ts +++ b/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()', diff --git a/tools/schematics/ng-add/schema.json b/tools/schematics/ng-add/schema.json index 70588364ec..f4451e1ad4 100644 --- a/tools/schematics/ng-add/schema.json +++ b/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" } } } \ No newline at end of file diff --git a/tools/schematics/ng-add/schema.ts b/tools/schematics/ng-add/schema.ts index 5ecaf6c812..291b70c239 100644 --- a/tools/schematics/ng-add/schema.ts +++ b/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'; } diff --git a/tools/schematics/utils/module-utils.ts b/tools/schematics/utils/module-utils.ts index 1f5da22e41..6fa9a0d90a 100644 --- a/tools/schematics/utils/module-utils.ts +++ b/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',