Migrating to Vendure v2.0

[michaelbromley]

Vendure v2 is now in beta and is available using the @next npm tag or by specifying a specific beta version like 2.0.0-beta.0

npx @vendure/create@next my-shop

This is a living document that will be updated throughout the beta phase as user feedback is gathered. When the final v2 release occurs, this information will be used as the basis of the official migration guide that will be featured in the Vendure docs.

If you run into issues not covered here, or have other feedback, please leave a comment below!

---

Migration consists of 2 main parts:

1. Migrate your database: The DB schema changes are covered by the @vendure/migrate-v2 tool - start with that to get your database schema migrated.
2. Migrate your TypeScript code: You'll need to update your TypeScript code (custom configuration & plugins) to account for the breaking changes covered by this document.

Dependency updates

Updates to Vendure's underlying dependencies may require changes in your code:

TypeScript

• v2 is built on TypeScript v4.9.5. You should update your TypeScript version to match this. Doing so is quite likely to reveal new compiler errors (as is usual with TypeScript minor release updates).
• If you are using ts-node, update it to the latest version
• If you are targeting ES2022 or ESNEXT in your tsconfig.json, you'll need to set "useDefineForClassFields": false. See this issue for more context.

Apollo Server

If you have any custom ApolloServerPlugins, the plugin methods must now return a Promise. Example

TypeORM

TypeORM 0.3.x introduced a large number of breaking changes. For a complete guide, see the TypeORM v0.3.0 release notes.

Here are the main API changes you'll likely need to make:

• You can no longer compare to null, you need to use the new IsNull() helper:

  + import { IsNull } from 'typeorm';
  
  - .find({ where: { deletedAt: null } })
  + .find({ where: { deletedAt: IsNull() } })

• The findOne() method returns null rather than undefined if a record is not found.
• The findOne() method no longer accepts an id argument. Lookup based on id must be done with a where` clause:

  - .findOne(variantId)
  + .findOne({ where: { id: variantId } })

• Where clauses must use an entity id rather than passing an entity itself:

  - .find({ where: { user } })
  + .find({ where: { user: { id: user.id } } })

• The findByIds() method has been deprecated. Use the new In helper instead:

  + import { In } from 'typeorm';
  
  - .findByIds(ids)
  + .find({ where: { id: In(ids) } })

Vendure TypeScript API Changes

Custom Order / Fulfillment / Payment processes

In v2, the hard-coded states & transition logic for the Order, Fulfillment and Payment state machines has been extracted from the core services and instead resides in a default OrdertProcess, FulfillmentProcess and PaymentProcess object. This allows you to really customize these flows without having to work around the assumptions & logic implemented by the default processes.

What this means is that if you are defining a custom process, you'll now need to explicitly add the default process to the array.

+ import { defaultOrderProcess } from '@vendure/core';

orderOptions: {
-  process: [myCustomOrderProcess],
+  process: [defaultOrderProcess, myCustomOrderProcess],
}

Also note that shippingOptions.customFulfillmentProcess and paymentOptions.customPaymentProcess are both now renamed to process. The old names are still usable but are deprecated.

OrderItem no longer exists

As a result of #1981, the OrderItem entity no longer exists. The function and data of OrderItem is now transferred to OrderLine. As a result, the following APIs which previously used OrderItem arguments have now changed:

• FulfillmentHandler
• ChangedPriceHandlingStrategy
• PromotionItemAction
• TaxLineCalculationStrategy

ProductVariant stock changes

With #1545 we have changed the way we model stock levels in order to support multiple stock locations. This means that the ProductVariant.stockOnHand and ProductVariant.stockAllocated properties no longer exist on the ProductVariant entity in TypeScript.

Instead, this information is now located at ProductVariant.stockLevels, which is an array of StockLevel entities.

Other breaking API changes

• ChannelService.findAll() now returns a PaginatedList<Channel> instead of Channel[].
• The Admin UI component vdr-product-selector has been renamed to vdr-product-variant-selector to more accurately represent what it does. If you are using vdr-product-selector if any ui extensions code, update it to use the new selector.
• Internal ErrorResult classes now take a single object argument rather than multiple args.
• All monetary values are now represented in the GraphQL APIs with a new Money scalar type. If you use graphql-code-generator, you'll want to tell it to treat this scalar as a number:

  import { CodegenConfig } from '@graphql-codegen/cli'
  
  const config: CodegenConfig = {
    schema: 'http://localhost:3000/shop-api',
    documents: ['src/**/*graphql.ts'],
    config: {
      scalars: {
        Money: 'number',
      },
    },
    generates: {
      // .. 
    }
  };

• If you are using the typescript-compatibility plugin to generate namespaced types, you'll need to drop this, as it is no longer maintained: https://the-guild.dev/blog/whats-new-in-graphql-codegen-v2#typescript-compatibility

• (v2.0.0-beta.1) A new Region entity has been introduced, which is a base class for Country and the new Province entity. The Zone.members property is now an array of Region rather than Country, since Zones may now be composed of both countries and provinces. If you have defined any custom fields on Country, you'll need to change it to Region in your custom fields config.

Shop API Changes

• The setOrderShippingMethod mutation now takes an array of IDs rather than a single ID (to support multi-vendor orders with split shipping)

  export const SET_SHIPPING_METHOD = gql`
  - mutation SetShippingMethod($id: ID!) {
  + mutation SetShippingMethod($id: [ID!]!) {
       setOrderShippingMethod(shippingMethodId: $id) {
           ... on Order {
               # ...
           }
       }
    }
  `;

[ivanjd]

Do you have an ETA for the stable release of 2.0. If we are new to vandure do you recommend starting on the prerelease of version 2 or on the last stable release of v1. If we start on the prerelease version and some major changes do occur will you have any guides on how to migrate. Thanks a lot.

[michaelbromley]

I am aiming to have the major breaking changes done by the end of February. At that point we'll probably go to 2.0.0-beta and keep breaking changes to a minimum.

Until the actual release, I intend to update this thread with guides to migrate across breaking pre-release changes. Then upon final release I'll consolidate this into a official migration guide.

[martijnvdbrug]

This might save some people headaches:

• Remove node_modules and reinstall when you get errors like Cannot find module '@ardatan/aggregate-error'
• Remove yarn.lock and reinstall if you are having trouble with Admin UI compilation

[yasserlens]

The docs don't mention OrderItemPriceCalculationStrategy being changed - although as the name suggests, this is an OrderItem strategy. Has this changed at all in V2?

[michaelbromley]

It actually didn't have a breaking change. I'm not sure if we need to rename - yes, there is no more OrderItem entity, but we can still think of a single unit of an OrderLine as an "item" I think. Maybe a better name could be OrderLinePriceCalculationStrategy or OrderLineUnitPriceCalculationStrategy 🤷

[yasserlens]

Yeah the name made me pause and look through the source code but I saw it there. Kept me thinking whether I'm missing something. A name change at some point, e.g. OrderLinePriceCalculationStrategy, will help with the confusion. Especially in future versions when references to "OrderItem" will disappear from documentation.

[martijnvdbrug]

If you are using productVariant.stockOnHand or any other stock references in your custom code, you need to migrate those parts of your code as well. This thread provides insight in to the V2 stock implementation: #1545

[michaelbromley]

Good point, I will add this to the main post.

[DanielBiegler]

• All monetary values are now represented in the GraphQL APIs with a new Money scalar type. If you use graphql-code-generator, you'll want to tell it to treat this scalar as a number:

  import { CodegenConfig } from '@graphql-codegen/cli'
  
  const config: CodegenConfig = {
    schema: 'http://localhost:3000/shop-api',
    documents: ['src/**/*graphql.ts'],
    scalars: {
      Money: 'number',
    },
    generates: {
      // .. 
    }
  };

This isnt quite correct @michaelbromley - scalars are a member of the field config inside the config object. See issue here

Just tried it out for the Remix Storefornt in the YAML config like this:

config:
  scalars:
    Money: number

Which successfully generates the new types, see the diff here 👍

[michaelbromley]

Thanks for the correction!

[martijnvdbrug]

Might be a bit late, but, related to the breaking Shop-API setOrderShippingMethod: Shouldn't the parameter also be renamed from shippingMethodId to shippingMethodIds? It's already breaking, so might as well 🙃

export const SET_SHIPPING_METHOD = gql`
 mutation SetShippingMethod($id: [ID!]!) {
-    setOrderShippingMethod(shippingMethodId: $id) {
+    setOrderShippingMethod(shippingMethodIds: $id) {
         ... on Order {
             # ...
         }
     }
  }
`;

[martijnvdbrug]

Upgrading from Jest to Vitest

If you are using Jest in your projects, and upgrade to Vendure version 2, you will probably run into some errors related to ESM. You could configure Jest to work with ES Modules, but I found it easier to install Vitest (which is also what Vendure Core is using to run tests).

Migrating from Jest to Vitest is pretty easy:

1. yarn add -D vitest
2. yarn remove jest @types/jest ts-jest
3. Remove Jest fromt your tsconfig.json

- "types": ["node", "jest"]
+ "types": ["node"]

4. Add these imports to your test files: import { expect, describe, beforeAll, afterAll, it, vi, test } from 'vitest';
5. You can now run your tests with yarn vitest run or keep Vitest in watch mode with yarn vitest

If you are using app.server.get() or similar code

If you are using NestJS providers or services in your code, for example for listening to the EventBus in your tests, you need to use SWC as compiler with vitest:

1. yarn add -D swc-core unplugin-swc
2. Create a file named vitest.config.ts in the same dir as your package.json with these contents:

import swc from 'unplugin-swc';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // testTimeout: 10000,
  },
  plugins: [
    // SWC required to support decorators used in test plugins
    // See https://github.com/vitest-dev/vitest/issues/708#issuecomment-1118628479
    // Vite plugin
    swc.vite({
      jsc: {
        transform: {
          // See https://github.com/vendure-ecommerce/vendure/issues/2099
          useDefineForClassFields: false,
        },
      },
    }),
  ],
});

3. You should now be able to run your tests, and depend on code like this in your e2e tests:

    server.app
      .get(EventBus)
      .ofType(OrderStateTransitionEvent)
      .subscribe((event) => {
        orderEvents.push(event);
      });

[martijnvdbrug]

Oops, just saw that this was already in the official docs: https://docs.vendure.io/developer-guide/testing/