Vendure Knowledge Patch

Vendure Knowledge Patch

Use this skill when implementing or upgrading a Vendure server, Shop or Admin API, Dashboard extension, storefront integration, payment or email integration, or operational tooling. Check the breaking-change notes first, then open only the reference that matches the work.

Reference index

Breaking changes and upgrade checks

Replace legacy asset MIME names

The unreleased line upgrades file-type to ^21.3.1. In explicit assetOptions.permittedFileTypes lists, replace the former x- names with:

• audio/flac
• video/matroska
• application/vnd.apache.arrow.file
• application/vnd.apache.parquet

The default wildcard list is unaffected.

Remove the default production password

From 3.7, production startup fails while the default superadmin password is configured.

Review email templates and transports

In 3.7, the email plugin moves from MJML 4 to 5 and nodemailer 6 to 9. Review custom templates and transports for compatibility.

Declare health-check dependencies directly

From 3.7, @nestjs/terminus is no longer supplied transitively. Custom health checks must declare it directly.

Account for case-insensitive coupon matching

From 3.7, promotion coupon matching is case-insensitive. This breaks stores that treated case variants as distinct coupon codes.

Replace deprecated Dashboard compatibility mode

DashboardPlugin is exported from @vendure/dashboard; the old AdminUiPlugin compatibilityMode is deprecated.

Security-critical upgrade notes

• 3.7.2 closes unauthorized draft-line adjustment, administrator password-reset privilege escalation, cross-channel Promotion and FacetValue deletion, and cross-channel Asset and StockLocation writes.
• 3.6.5 addresses Dashboard XSS, SQLite list-query denial of service, and Shop API list-data exposure.
• 3.6.4 addresses asset-import SSRF.
• 3.6.2 addresses languageCode and Postgres-search SQL injection.
• 3.5.3 addresses native-auth timing enumeration.

Read security-and-access.md when the work touches authentication, authorization, channel boundaries, proxy trust, password validation, or customer assignment.

Required migrations

• The 3.4 Settings Store requires a new table.
• 3.4 adds indexes for Order.orderPlacedAt and JobItem.createdAt.
• DefaultCachePlugin users upgrading through 3.2 need precision(3) on CacheItem.expiresAt.
• 3.6 provides migrateAssetTranslationData() for the asset-translation change.

Authentication and authorization

External account linking

A custom AuthenticationStrategy must return verified: true for a provider-verified email before an external login can link to an existing account. Creating a new account is unaffected.

API keys and entity access

3.6 adds core API-key authentication and Dashboard key management. API-key sessions resolve their Administrator through the key owner. EntityAccessControlStrategy is the extension point for row-level access control.

Settings Store

3.4 introduces SettingsStore for global and scoped configuration. Read and write permissions are added later, and a Dashboard management page arrives in 3.6.

Since 3.4.2, prefer the context-first service signatures; the old order remains temporarily accepted:

SettingsStoreService.get<T>(ctx, key)
SettingsStoreService.getMany(ctx, keys)
SettingsStoreService.set<T>(ctx, key, value)
SettingsStoreService.setMany(ctx, values)

Channel-aware catalog rules

• Product lookup by slug is channel-scoped.
• assignProductsToChannel assigns the Product and its variants.
• Assigning a variant to a channel seeds a StockLevel.
• New variants inherit every channel of their Product.
• Numeric stockOnHand writes target the active channel's stock location.
• In 3.6, ProductOptionGroup and ProductOption are shared, channel-aware entities; CSV import supports shared option groups, and the Dashboard has an Option Groups management page.

Order and checkout behavior

• The Shop API adds addItemsToOrder and a mutation for changing the active order's currency.
• AddPaymentToOrderResult can return CouponRemovedDuringCheckoutError when checkout invalidates a coupon.
• OrderTaxCalculationStrategy configures order-level tax calculation.
• OrderLineDiscountDistributionStrategy controls discount proration.
• OrderMergeStrategy may be asynchronous.
• OrderService.mergeOrders() is atomic and concurrency-safe.
• State-machine transitions roll back atomically when a hook fails.

Read orders-checkout-and-payments.md before changing promotion usage, tax, payment eligibility, shipping, or order event handling.

Dashboard entry points

• New projects include the React Dashboard and can optionally scaffold a Next.js storefront.
• Generated Dashboard configuration uses API URL auto.
• Scaffolded projects read the server port from VENDURE_SERVER_PORT.
• Dashboard builds support Vite 7, user stylesheets, and opt-in pre-bundling through useExperimentalBundle.
• Extensions can add unauthenticated routes, TanStack Router validateSearch, router-plugin options, bearer-token authentication, and custom React providers.

Open dashboard-and-project-tooling.md for shell extension points, permissions, forms, queries, tables, bulk actions, saved views, and merchant workflows.

Operations and integration entry points

• ApiOptions accepts trustProxy.
• BootstrappedEvent signals server readiness, and onBeforeAppListen exposes the Nest application immediately before listening starts.
• Scheduled tasks can be triggered manually, receive a RequestContext, and include a built-in database job-cleanup task.
• Job options support priority; BullMQ honors configured Redis prefixes for queue and buffer storage.
• 3.3 introduces @vendure/telemetry-plugin and tracing across services, cache, scheduled tasks, and job queues.
• Email generators may be asynchronous, and SMTPTransportOptions accepts pooled-SMTP settings.