@vendure/docs 0.0.0-202601161541

package/docs/guides/developer-guide/migrating-from-v1/breaking-api-changes.md

@@ -0,0 +1,213 @@
+---
+title: "Breaking API Changes"
+sidebar_position: 3
+---
+
+# Breaking API Changes
+
+## Breaks from updated dependencies
+
+### 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](https://github.com/vendurehq/vendure/issues/2099) for more context.
+
+### Apollo Server & GraphQL
+If you have any custom ApolloServerPlugins, the plugin methods must now return a Promise. Example:
+
+```diff
+export class TranslateErrorsPlugin implements ApolloServerPlugin {
+   constructor(private i18nService: I18nService) {}
+
+-  requestDidStart(): GraphQLRequestListener {
++  async requestDidStart(): Promise<GraphQLRequestListener> {
+     return {
+-      willSendResponse: requestContext => {
++      willSendResponse: async requestContext => {
+         const { errors, context } = requestContext;
+         if (errors) {
+           (requestContext.response as any).errors = errors.map(err => {
+             return this.i18nService.translateError(context.req, err as GraphQLError) as any;
+           });
+         }
+       },
+     };
+   }
+}
+```
+
+With the update to GraphQL v16, you might run into issues with other packages in the GraphQL ecosystem that also depend on the `graphql` package, such as `graphql-code-generator`. In this case these packages will also need to be updated.
+
+For instance, 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).
+
+### TypeORM
+TypeORM 0.3.x introduced a large number of breaking changes. For a complete guide, see the [TypeORM v0.3.0 release notes](https://github.com/typeorm/typeorm/releases/tag/0.3.0). 
+
+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:
+    ```diff
+    + 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:
+    ```diff
+    - .findOne(variantId)
+    + .findOne({ where: { id: variantId } })
+    ```
+- Where clauses must use an entity id rather than passing an entity itself:
+    ```diff
+    - .find({ where: { user } })
+    + .find({ where: { user: { id: user.id } } })
+    ```
+- The `findByIds()` method has been deprecated. Use the new `In` helper instead:
+    ```diff
+    + 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 reside in a default `OrderProcess`, `FulfillmentProcess` and `PaymentProcess` object. This allows you to _fully_ 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.
+
+```diff
++ 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](https://github.com/vendurehq/vendure/issues/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`
+
+If you have implemented any of these APIs, you'll need to check each one, remove the `OrderItem` argument from any methods that are using it,
+and update any logic as necessary.
+
+You may also be joining the OrderItem relation in your own TypeORM queries, so you'll need to check for code like this:
+
+```diff
+const order = await this.connection
+  .getRepository(Order)
+  .createQueryBuilder('order')
+  .leftJoinAndSelect('order.lines', 'line')
+- .leftJoinAndSelect('line.items', 'items')
+```
+
+or 
+
+```diff
+const order = await this.connection
+  .getRepository(Order)
+  .findOne(ctx, orderId, {
+-    relations: ['lines', 'lines.items'],
++    relations: ['lines'],
+  });
+```
+
+### ProductVariant stock changes
+
+With [#1545](https://github.com/vendurehq/vendure/issues/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](/reference/typescript-api/entities/stock-level) entities.
+
+### New return type for Channel, TaxCategory & Zone lists
+
+- The `ChannelService.findAll()` method now returns a `PaginatedList<Channel>` instead of `Channel[]`. 
+- The `channels` GraphQL query now returns a `PaginatedList` rather than a simple array of Channels.
+- The `TaxCategoryService.findAll()` method now returns a `PaginatedList<TaxCategory>` instead of `TaxCategory[]`.
+- The `taxCategories` GraphQL query now returns a `PaginatedList` rather than a simple array of TaxCategories.
+- The `ZoneService.findAll()` method now returns a `PaginatedList<Zone>` instead of `Zone[]`. The old behaviour of `ZoneService.findAll()` (all Zones, cached for rapid access) can now be found under the new `ZoneService.getAllWithMembers()` method.
+- The `zones` GraphQL query now returns a `PaginatedList` rather than a simple array of Zones. 
+
+### Admin UI changes
+
+If you are using the `@vendure/ui-devkit` package to generate custom ui extensions, here are the breaking changes to be aware of:
+
+- As part of the major refresh to the Admin UI app, certain layout elements had be changed which can cause your custom routes to look bad. Wrapping all your custom pages in `<vdr-page-block>` (or `<div class="page-block">` if not built with Angular components) will improve things. There will soon be a comprehensive guide published on how to create seamless ui extensions that look just like the built-in screens.
+- If you use any of the scoped method of the Admin UI `DataService`, you might find that some no longer exist. They are now deprecated and will eventually be removed. Use the `dataService.query()` and `dataService.mutation()` methods only, passing your own GraphQL documents:
+   ```ts
+    // Old way
+   this.dataService.product.getProducts().single$.subscribe(...);
+   ```
+   ```ts
+    // New way
+   const GET_PRODUCTS = gql`
+     query GetProducts {
+       products {
+         items {
+           id
+           name
+           # ... etc
+         }
+       }
+     }
+   `;
+   this.dataService.query(GET_PRODUCTS).single$.subscribe(...);
+   ```
+- 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.
+
+### Other breaking API changes
+- **End-to-end tests using Jest** will likely run into issues due to our move towards using some dependencies that make use of ES modules. We have found the best solution to be to migrate tests over to [Vitest](https://vitest.dev), which can handle this and is also significantly faster than Jest. See the updated [Testing guide](/guides/developer-guide/testing) for instructions on getting started with Vitest.
+- 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](https://the-guild.dev/graphql/codegen), you'll want to tell it to treat this scalar as a number:
+    ```ts
+    import { CodegenConfig } from '@graphql-codegen/cli'
+ 
+    const config: CodegenConfig = {
+      schema: 'http://localhost:3000/shop-api',
+      documents: ['src/**/*graphql.ts'],
+      config: {
+        scalars: {
+          Money: 'number',
+        },
+      },
+      generates: {
+        // .. 
+      }
+    };
+    ```
+- 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.
+- If you are using the **s3 storage strategy** of the AssetServerPlugin, it has been updated to use v3 of the AWS SDKs. This update introduces an [improved modular architecture to the AWS sdk](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/), resulting in smaller bundle sizes. You need to install the `@aws-sdk/client-s3` & `@aws-sdk/lib-storage` packages, and can remove the `aws-sdk` package. If you are using it in combination with MinIO, you'll also need to rename a config property and provide a region:
+   ```diff
+   nativeS3Configuration: {
+      endpoint: 'http://localhost:9000',
+   -  s3ForcePathStyle: true,
+   +  forcePathStyle: true,
+      signatureVersion: 'v4',
+   +  region: 'eu-west-1',
+   }
+   ```
+- The **Stripe plugin** has been made channel aware. This means your api key and webhook secret are now stored in the database, per channel, instead of environment variables.
+   To migrate to v2 of the Stripe plugin from @vendure/payments you need to:
+  1. Remove the apiKey and webhookSigningSecret from the plugin initialization in vendure-config.ts:
+       ```diff
+       StripePlugin.init({
+       -  apiKey: process.env.YOUR_STRIPE_SECRET_KEY,
+       -  webhookSigningSecret: process.env.YOUR_STRIPE_WEBHOOK_SIGNING_SECRET,
+          storeCustomersInStripe: true,
+       }),
+       ```
+  2. Start the server and login as administrator. For each channel that you'd like to use Stripe payments, you need to create a payment method with payment handler Stripe payment and the apiKey and webhookSigningSecret belonging to that channel's Stripe account.
+- If you are using the **BullMQJobQueuePlugin**, the minimum Redis recommended version is 6.2.0.
+- The `WorkerHealthIndicator` which was deprecated in v1.3.0 has been removed, as well as the `jobQueueOptions.enableWorkerHealthCheck` config option.
+- The `CustomerGroupEntityEvent` (fired on creation, update or deletion of a CustomerGroup) has been renamed to `CustomerGroupEvent`, and the former `CustomerGroupEvent` (fired when Customers are added to or removed from a group) has been renamed to `CustomerGroupChangeEvent`.
+- We introduced the [plugin compatibility API](/guides/developer-guide/plugins/#step-7-specify-compatibility) to allow plugins to indicate what version of Vendure they are compatible with. To avoid bootstrap messages you should add this property to your plugins.

package/docs/guides/developer-guide/migrating-from-v1/database-migration.md

@@ -0,0 +1,39 @@
+---
+title: "Database Migration"
+sidebar_position: 2
+---
+
+# v2 Database Migration
+
+Vendure v2 introduces a number of breaking changes to the database schema, some of which require quite complex migrations in order to preserve existing data. To make this process as smooth as possible, we have created a migration tool which will handle the hard parts for you!
+
+:::warning
+**Important!** It is _critical_ that you back up your production data prior to attempting this migration.
+
+**Note for MySQL/MariaDB users:** transactions for migrations are [not supported by these databases](https://dev.mysql.com/doc/refman/5.7/en/cannot-roll-back.html). This means that if the migration fails for some reason, the statements that have executed will not get rolled back, and your DB schema can be left in an inconsistent state from which is it can be hard to recover. Therefore, it is doubly critical that you have a good backup that you can easily restore prior to attempting this migration.
+:::
+
+1. Make sure all your Vendure packages to the latest v2 versions.
+2. Use your package manager to install the [v2 migration tool](https://github.com/vendurehq/v2-migration-tool): `npm install @vendure/migrate-v2`
+    - Note, if you run into the error `"Cannot find module '@ardatan/aggregate-error'"`, delete node_modules and the lockfile and reinstall.
+3. Add the `MigrationV2Plugin` to your plugins array:
+   ```ts
+   import { MigrationV2Plugin } from '@vendure/migrate-v2';
+   
+   //...
+   const config: VendureConfig = {
+     //..
+     plugins: [
+       MigrationV2Plugin,
+     ]
+   }
+   ```
+   The sole function of this plugin is to temporarily remove some "NOT NULL" constraints from certain columns, which allows us to run the next part of the migration.
+4. Generate a new migration file, `npm run migration:generate v2`
+5. Edit the newly-created migration file by following the comments in these examples: 
+    - [postgres](https://github.com/vendurehq/v2-migration-tool/blob/master/src/migrations/1686649098749-v201-postgres.ts)
+    - [mysql](https://github.com/vendurehq/v2-migration-tool/blob/master/src/migrations/1686655918823-v201-mysql.ts)
+
+   In your migrations files, you'll import the `vendureV2Migrations` from `@vendure/migrate-v2`.
+6. Run the migration with `npm run migration:run`.
+7. Upon successful migration, remove the `MigrationV2Plugin` from your plugins array, and generate _another_ migration. This one will add back the missing "NOT NULL" constraints now that all your data has been successfully migrated.

package/docs/guides/developer-guide/migrating-from-v1/index.md

@@ -0,0 +1,41 @@
+---
+title: "Migrating from v1"
+weight: 2
+sidebar_position: 1
+---
+
+# Migrating from Vendure 1 to 2
+
+This section contains guides for migrating from Vendure v1 to v2.
+
+There are a number of breaking changes between the two versions, which are due to a few major factors:
+
+1. To support new features such as multi-vendor marketplace APIs and multiple stock locations, we had to make some changes to the database schema and some of the internal APIs.
+2. We have updated all of our major dependencies to their latest versions. Some of these updates involve breaking changes in the dependencies themselves, and in those cases where you are using those dependencies directly (most notably TypeORM), you will need to make the corresponding changes to your code.
+3. We have removed some old APIs which were previously marked as "deprecated".
+
+## Migration steps
+
+Migration will consist of these main steps:
+
+1. **Update your Vendure dependencies** to the latest versions
+   ```diff
+   {
+     // ...
+     "dependencies": {
+   -    "@vendure/common": "1.9.7",
+   -    "@vendure/core": "1.9.7",
+   +    "@vendure/common": "2.0.0",
+   +    "@vendure/core": "2.0.0",
+        // etc.
+     },
+     "devDependencies": {
+   -    "typescript": "4.3.5",
+   +    "typescript": "4.9.5",
+        // etc.
+     }
+   }
+   ```
+2. **Migrate your database**. This is covered in detail in the [database migration section](/guides/developer-guide/migrating-from-v1/database-migration).
+3. **Update your custom code** (configuration, plugins, admin ui extensions) to handle the breaking changes. Details of these changes are covered in the [breaking API changes section](/guides/developer-guide/migrating-from-v1/breaking-api-changes).
+4. **Update your storefront** to handle some small breaking changes in the Shop GraphQL API. See the [storefront migration section](/guides/developer-guide/migrating-from-v1/storefront-migration) for details.

package/docs/guides/developer-guide/migrating-from-v1/storefront-migration.md

@@ -0,0 +1,30 @@
+---
+title: "Storefront Migration"
+sidebar_position: 4
+---
+
+# Storefront migration
+
+There are relatively few breaking changes that will affect the storefront.
+
+- The `setOrderShippingMethod` mutation now takes an array of shipping method IDs rather than just a single one. This is so we can support multiple shipping methods per Order.
+   ```diff
+   -mutation setOrderShippingMethod($shippingMethodId: ID!) {
+   +mutation setOrderShippingMethod($shippingMethodId: [ID!]!) {
+     setOrderShippingMethod(shippingMethodId: $shippingMethodId) {
+       # ... etc
+     }
+   } 
+   ```
+- The `OrderLine.fulfillments` field has been changed to `OrderLine.fulfillmentLines`. Your storefront may be using this when displaying the details of an Order.
+- If you are using the `graphql-code-generator` package to generate types for your storefront, all monetary values such as `Order.totalWithTax` or `ProductVariant.priceWithTax` are now represented by the new `Money` scalar rather than by an `Int`. You'll need to tell your codegen about this scalar and configure it to be interpreted as a number type:
+   ```diff
+   documents:
+     - "app/**/*.{ts,tsx}"
+     - "!app/generated/*"
+   +config:
+   +  scalars:
+   +    Money: number
+   generates:
+     # ... etc
+   ```

package/docs/guides/developer-guide/migrations/index.md

@@ -0,0 +1,197 @@
+---
+title: "Migrations"
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Database migrations are needed whenever the database schema changes. This can be caused by:
+
+* changes to the [custom fields](/guides/developer-guide/custom-fields/) configuration
+* new [database entities defined by plugins](/guides/developer-guide/database-entity/)
+* occasional changes to the core Vendure database schema when updating to newer versions
+
+## Synchronize vs migrate
+
+TypeORM (which Vendure uses to interact with the database) has a `synchronize` option which, when set to `true`, will automatically update your database schema to reflect the current Vendure configuration. This is equivalent to automatically generating and running a migration _every time_ the server starts up.
+
+This is convenient while developing, but **should not be used in production**, since a misconfiguration could potentially delete production data. In this case, migrations should be used.
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    dbConnectionOptions: {
+        // ...
+        // highlight-next-line
+        synchronize: false,
+    }
+};
+```
+
+## Migration workflow
+
+This section assumes a standard Vendure installation based on `@vendure/create`. 
+
+Let's assume you have defined a new "keywords" custom field on the Product entity. The next time you start your server you'll see a message like this:
+
+```bash
+[server] Your database schema does not match your current configuration. Generate a new migration for the following changes:
+[server]  - ALTER TABLE "product" ADD "customFieldsKeywords" character varying(255)
+```
+
+Since we have `synchronize` set to `false`, we need to generate a migration to apply these changes to the database. The workflow for this is as follows:
+
+### 1. Generate a migration
+
+:::cli
+Run `npx vendure migrate` and select "Generate a new migration"
+:::
+
+### 2. Check the migration file
+
+This will have created a new migration file in the `src/migrations` directory. Open this file and check that it looks correct. It should look something like this:
+
+```ts title="src/migrations/1690558104092-add-keywords-field.ts"
+import {MigrationInterface, QueryRunner} from "typeorm";
+
+export class addKeywordsField1690558104092 implements MigrationInterface {
+
+   public async up(queryRunner: QueryRunner): Promise<any> {
+        await queryRunner.query(`ALTER TABLE "product" ADD "customFieldsKeywords" character varying(255)`, undefined);
+   }
+
+   public async down(queryRunner: QueryRunner): Promise<any> {
+        await queryRunner.query(`ALTER TABLE "product" DROP COLUMN "customFieldsKeywords"`, undefined);
+   }
+
+}
+```
+
+The `up()` function is what will be executed when the migration is run. The `down()` function is what will be executed if the migration is reverted. In this case, the `up()` function is adding a new column to the `product` table, and the `down()` function is removing it.
+
+:::note
+The exact query will depend on the database you are using. The above example is for PostgreSQL.
+:::
+
+### 3. Run the migration
+
+Assuming the migration file looks correct, the next time you start the server, the migration will
+be run automatically. This is because the `runMigrations` function is called in the `src/index.ts` file:
+
+```ts title="src/index.ts"
+import { bootstrap, runMigrations } from '@vendure/core';
+import { config } from './vendure-config';
+
+// highlight-next-line
+runMigrations(config)
+    .then(() => bootstrap(config))
+    .catch(err => {
+        console.log(err);
+    });
+```
+
+It is also possible to run the migration manually without starting the server:
+
+:::cli
+Run `npx vendure migrate` and select "Run pending migrations"
+:::
+
+:::caution
+TypeORM will attempt to run each migration inside a transaction. This means that if one of the migration commands fails, then the entire transaction will be rolled back to its original state.
+
+_However_ this is **not supported by MySQL / MariaDB**. This means that when using MySQL or MariaDB, errors in your migration script could leave your database in a broken or inconsistent state. Therefore it is **critical** that you first create a backup of your database before running a migration.
+
+You can read more about this issue in [typeorm/issues/7054](https://github.com/typeorm/typeorm/issues/7054)
+:::
+
+## Migrations in-depth
+
+Now we'll dive into what's going on under the hood.
+
+Vendure exposes a some helper function which wrap around the underlying [TypeORM migration functionality](https://typeorm.io/migrations). The 
+reason for using these helper functions rather than using the TypeORM CLI directly is that Vendure generates additional 
+schema information based on custom fields and plugin configurations which are not available to the TypeORM CLI.
+
+In a standard Vendure installation prior to v2.2.0, you'll see the following migration script in your project root directory.
+Running the `vendure migrate` command also uses a very similar script internally.
+
+```ts title="migration.ts"
+import { generateMigration, revertLastMigration, runMigrations } from '@vendure/core';
+import { Command } from 'commander';
+
+import { config } from './src/vendure-config';
+
+const program = new Command();
+
+program
+    .command('generate <name>')
+    .description('Generate a new migration file with the given name')
+    .action(name => {
+        return generateMigration(config, { name, outputDir: './src/migrations' });
+    });
+
+program
+    .command('run')
+    .description('Run all pending migrations')
+    .action(() => {
+        return runMigrations(config);
+    });
+
+program
+    .command('revert')
+    .description('Revert the last applied migration')
+    .action(() => {
+        return revertLastMigration(config);
+    });
+
+program.parse(process.argv);
+```
+
+and a set of scripts in your `package.json` file:
+
+```json
+{
+  // ...
+  "scripts": {
+    "migration:generate": "ts-node migration.ts generate",
+    "migration:run": "ts-node migration.ts run",
+    "migration:revert": "ts-node migration.ts revert"
+  }
+}
+```
+
+When running and reverting migrations, Vendure is looking for migration files in the directory specified by the `dbConnectionOptions.migrations` option is set in your VendureConfig:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import path from 'path';
+
+export const config: VendureConfig = {
+    // ...
+    dbConnectionOptions: {
+        // ...
+        // highlight-next-line
+        migrations: [path.join(__dirname, './migrations/*.+(js|ts)')],
+    }
+};
+```
+
+TypeORM keeps track of which migrations have been run by creating a new `migrations` table in your database, and each time a migration is successfully run
+it adds a row to this table with the name of the migration class and a timestamp. This prevents the same migration from being run twice, and also allows
+TypeORM to know which migration to revert when the `revertLastMigration` function is called.
+
+![Migrations table](./migration.webp)
+
+These are the underlying function exposed by Vendure which are used to generate, run and revert migrations:
+
+- [`generateMigration` function](/reference/typescript-api/migration/generate-migration/)
+- [`runMigrations` function](/reference/typescript-api/migration/run-migrations/)
+- [`revertLastMigration` function](/reference/typescript-api/migration/revert-last-migration/)
+
+### Reverting a migration
+
+The `revertLastMigration` function will revert the last applied migration by applying the `down()` method. If run again it will then revert the one before that, and so on.
+In doing so, it will also remove the corresponding row from the `migrations` table.
+

package/docs/guides/developer-guide/nest-devtools/index.md

@@ -0,0 +1,74 @@
+---
+title: "Nest Devtools"
+---
+
+The NestJS core team have built a [powerful set of dev tools](https://docs.nestjs.com/devtools/overview) which can be used to inspect, analyze and debug NestJS applications.
+Since a Vendure server is a NestJS application, these tools can be used to debug your Vendure application.
+
+:::note
+Nest Devtools is a paid service. You can [sign up for a free trial](https://devtools.nestjs.com/).
+:::
+
+## Installation
+
+First you'll need to install the `@nestjs/devtools-integration` package:
+
+```bash
+npm i @nestjs/devtools-integration
+```
+
+## Configuration
+
+Next you need to create a plugin which imports the `DevToolsModule` and adds it to the `imports` array:
+
+```ts title="src/plugins/devtools/devtools-plugin.ts"
+import { VendurePlugin } from '@vendure/core';
+import { DevtoolsModule } from '@nestjs/devtools-integration';
+
+@VendurePlugin({
+    imports: [
+        DevtoolsModule.register({
+            // The reason we are checking the NODE_ENV environment 
+            // variable here is that you should never use this module in production!
+            http: process.env.NODE_ENV !== 'production',
+        }),
+    ],
+})
+class DevtoolsPlugin {}
+```
+
+Now we need to add this plugin to the `plugins` array in the `VendureConfig`. We need to make sure we are
+only adding it to the server config, and not the worker, otherwise we will get a port config when
+running the server and worker at the same time.
+
+Lastly we must set the `snapshot` option when bootstrapping the server. Note: this is only possible
+with Vendure v2.2 or later.
+
+```ts title="src/index.ts"
+import { bootstrap } from '@vendure/core';
+import { config } from './vendure-config';
+
+const configWithDevtools = {
+    ...config,
+    plugins: [
+        ...config.plugins,
+        DevtoolsPlugin,
+    ],
+};
+
+bootstrap(configWithDevtools, {
+    nestApplicationOptions: { snapshot: true } 
+})
+    .catch(err => {
+        console.log(err);
+        process.exit(1);
+    });
+```
+
+## Usage
+
+Now you can start the server, and navigate to [devtools.nestjs.com](https://devtools.nestjs.com/) to start view your
+Vendure server in the Nest Devtools dashboard.
+
+![Nest Devtools graphql explorer](./nest-devtools-graph.webp)
+![Nest Devtools bootstrap performance](./nest-devtools-bootstrap-perf.webp)

package/docs/guides/developer-guide/overview/index.md

@@ -0,0 +1,40 @@
+---
+title: "Vendure Overview"
+sidebar_position: 2
+---
+
+Read this page to gain a high-level understanding of Vendure and concepts you will need to know to build your application.
+
+## Architecture
+
+Vendure is a headless e-commerce platform. By "headless" we mean that it exposes all of its functionality via APIs. Specifically, Vendure features two GraphQL APIs: one for storefronts (Shop API) and the other for administrative functions (Admin API).
+
+These are the major parts of a Vendure application:
+
+* **Server**: The Vendure server is the part that handles requests coming in to the GraphQL APIs. It serves both the [Shop API](/reference/graphql-api/shop/queries) and [Admin API](/reference/graphql-api/admin/queries), and can send jobs to the Job Queue to be processed by the Worker.
+* **Worker**: The Worker runs in the background and deals with tasks such as updating the search index, sending emails, and other tasks which may be long-running, resource-intensive or require retries.
+* **Dashboard**: The Dashboard is how shop administrators manage orders, customers, products, settings and so on. The Dashboard can be further extended to support custom functionality, as detailed in the [Extending the Dashboard](/guides/extending-the-dashboard/extending-overview/) section
+* **Storefront**: With headless commerce, you are free to implement your storefront exactly as you see fit, unconstrained by the back-end, using any technologies that you like. To make this process easier, we have created a number of [storefront starter kits](/guides/storefront/storefront-starters/), as well as [guides on building a storefront](/guides/storefront/connect-api/).
+
+![./Vendure_docs-architecture.webp](./Vendure_docs-architecture.webp) 
+
+## Technology stack
+
+Vendure is built on the following open-source technologies:
+
+- **SQL Database**: Vendure requires an SQL database compatible with [TypeORM](https://typeorm.io/). Officially we support **PostgreSQL**, **MySQL/MariaDB** and **SQLite** but Vendure can also be used with API-compatible variants such [Amazon Aurora](https://aws.amazon.com/rds/aurora/), [CockroachDB](https://www.cockroachlabs.com/), or [PlanetScale](https://planetscale.com/).
+- **TypeScript & Node.js**: Vendure is written in [TypeScript](https://www.typescriptlang.org/) and runs on [Node.js](https://nodejs.org).
+- **NestJS**: The underlying framework is [NestJS](https://nestjs.com/), which is a full-featured application development framework for Node.js. Building on NestJS means that Vendure benefits from the well-defined structure and rich feature-set and ecosystem that NestJS provides.
+- **GraphQL**: The Shop and Admin APIs use [GraphQL](https://graphql.org/), which is a modern API technology which allows you to specify the exact data that your client application needs in a convenient and type-safe way. Internally we use [Apollo Server](https://www.apollographql.com/docs/apollo-server/) to power our GraphQL APIs.
+- **React**: The Dashboard is built with [React](https://react.dev/), as well as other popular front-end technologies such as TailwindCSS.
+
+## Design principles
+
+Vendure is designed to be:
+
+- **Flexible**: Vendure is designed to be flexible enough to support a wide range of e-commerce use-cases, while taking care of the common functionality for you. It is not a "one-size-fits-all" solution, but rather a framework which you can extend and customize to suit your needs.
+- **Extensible**: A typical e-commerce application needs to integrate with many external systems for payments, shipping, inventory management, email sending, and so on. Vendure makes heavy use of the **strategy pattern** - a software design pattern which allows you to replace default behaviors with your own custom implementations as needed.
+- **Modular**: Vendure is built with a modular architecture, where each unit of functionality of your application is encapsulated in a **plugin**. This makes it easy to add or remove functionality as needed, and to share plugins with the community.
+- **Type-safe**: Vendure is written in TypeScript, which means that you get the benefits of static type-checking and code completion in your IDE. Our use of GraphQL for our APIs brings static typing to the API layer, enabling rapid development with type-safety across the entire stack.
+
+