evershopcommerce/evershop v2.3.0 on GitHub

A feature release on top of v2.2.2: outbound webhooks, a country-aware address system, a unified payment capture/void/refund flow with a rebuilt PayPal integration, redesigned transactional emails, a media library, and storefront building blocks for theme authors. It includes everything in v2.2.2 (a start-up fix and several security fixes).

This release contains breaking changes and 6 new database migrations, one of which renames address columns. Please read Breaking Changes and Upgrade Notes before upgrading. If you upgrade from v2.2.1 or earlier, also read the Upgrade Notes of v2.2.2 below.

Highlights

Webhooks — a new webhook module: send signed events to up to 10 HTTPS endpoints, with retries and a delivery log.
Address Format Registry — country-aware address forms, validation, storage and display, driven by one format record per country.
Unified payments — one capture / void / refund flow for every payment method, and a rebuilt PayPal integration (webhook, refunds, reconciliation).
Emails — a shared email layout, plus new refund and cancellation emails, in 17 languages.
Media library — a paginated, redesigned file browser with rename and paste-to-upload.
Theme building blocks — layouts.json, storefront pages split into movable blocks, shared widget typography hooks, theme assets and seed content.

Breaking Changes

Four changes that also affect you when upgrading from v2.2.1 shipped in v2.2.2 and are described there: raw SQL needs sql(), getContextValue(...) takes data literals only, Query.order(uuid) needs proven access, and API route middleware is authenticated.

Address columns were renamed (Address Format Registry). On customer_address, cart_address and order_address: full_name → recipient, address_1 → address_line_1, address_2 → address_line_2, city → locality, province → administrative_area, postcode → postal_code; seven nullable columns were added (organization, address_line_3, dependent_locality, sorting_code, given_name, family_name, extra). tax_rate.province / postcode became administrative_area / postal_code, and shipping_zone_province became shipping_zone_region. The migrations rename only (no row is rewritten), but v2.2.1 and v2.2.2 code do not work with the new schema: they still start, but every address reads back empty. The GraphQL Address types and the address REST payloads changed with them, and the types/customerAddress and lib/locale/countries modules were removed (use @evershop/evershop/lib/address: getCountries, getCountryName, isKnownCountry and the address types). Custom SQL, extensions and themes that read the old names must be updated. A script that reverses the address renames only is in the repository at scripts/address-formats/rollback-schema.sql.
Payment capture and refund routes were replaced by one contract. Removed: POST /api/stripe/paymentIntents/capture, POST /api/stripe/paymentIntents/refund, POST /api/cod/captures, POST /api/paypal/authorizations/capture, POST /api/paypal/authorizedTransactions, POST /api/paypal/captureTransactions and the PayPal refund route, together with the per-method admin buttons. Use POST /api/orders/:id/capture and POST /api/orders/:id/refunds (admin only); the order page shows generic Capture and Refund buttons. Payment methods now declare optional capture, void and refund handlers in registerPaymentMethod. Cash on Delivery orders get their own cod_* statuses, and a migration moves existing awaiting-payment COD orders from pending to cod_pending and records an offline authorize transaction for them. The order status no longer changes.
PayPal return page renamed: /paypal/proccessing is now /paypal/processing (no alias).
Storefront pages are now a shell plus blocks. The product, category, cart, checkout, account, order list, blog and search pages keep only the query, the provider and the Areas; every piece is its own page component that registers into a slot at its old position, so the default markup is unchanged. A theme that forked ProductView.tsx, CategoryView.tsx, ProductSingleForm.tsx, ShoppingCart.tsx, Checkout.tsx, MyAccount.tsx, OrderList.tsx, a blog page shell or SearchPage.tsx must delete the inline pieces from its copy, or the page renders them twice.
Public ?limit= is capped at system.max_collection_size (default 200, the largest admin grid option).
Fresh installs no longer create sample data. The install migration no longer creates the Men / Women / Kids categories or the Color and Size attributes with their options. Existing stores keep what they have. Themes supply their own catalogue through themes/<id>/seed/*.json, read only by evershop seed.
sanitize-html was replaced by xss for rich text. The allow-list is the same; serialization differs cosmetically (<br> instead of <br />), and style values containing url(javascript:) or expression() are now dropped. Code that imported sanitize-html through EverShop must declare it itself.
Prices and dates follow the active locale (the request locale, then the Store Setting language, then shop.language). Admin pages format in the admin language.

New Features

Webhooks (new `webhook` core module)

Admin → Settings → Webhooks: up to 10 webhooks, each with an HTTPS URL, a signing secret and a list of events (21 event topics, grouped in the form). Includes a test event, a delivery list with filters, a payload viewer and Retry.
Delivery is write-first: a webhook_delivery row is stored, sent, and retried from that row (after 1, 5, 30 and 120 minutes, 5 attempts). The row is both the retry queue and the admin log. Delivery is at-least-once; a 2xx response within 10 seconds counts as success. Failed deliveries are kept 30 days; completed ones up to webhookLogLimit (default 100) per webhook.
Each request is signed: X-EverShop-Signature: t=<unix>,v1=<HMAC-SHA256> over <timestamp>.<body>; X-EverShop-Delivery stays the same across retries. password is removed from payloads at any depth.
Only HTTPS and public addresses are allowed, checked at connect time. Set system.webhook.allowPrivateNetworks to allow local receivers.
Extensions can add topics with addProcessor('webhookTopics'). Translated into all 17 languages.
Event subscribers placed in subscribers/_all/ now receive every event, and every subscriber gets { name, uuid } as an optional second argument. Delivery of ordinary subscribers is unchanged (at-most-once).

Address Format Registry

One country format record (Google libaddressinput shape) now drives the storefront form, server validation, display, GraphQL, emails and every integration mapping. The checkout and the account address book use one schema-driven form with country-specific fields, region lists, telephone and postal patterns.
Admin: Settings → Customer (name format, telephone, company, address lines, required fields, default country) and Sell to countries on Settings → Shipping, with a confirmation that lists shipping zones that would be left without a country.
Shipment emails now print the delivery address.
Public API for extensions: @evershop/evershop/lib/address (patchAddressFormat, registerRegionProvider, registerAddressField, resolveAddressSchema, validateAddress, formatAddress, toIntegrationAddress). Registration is locked after bootstrap, like the other registries.
The package now ships a NOTICE file for the bundled address data (derived from Google's libaddressinput).

Payments

Unified operations. Capture, void and refund are owned by core (captureOrder, refundOrder) and work the same for every payment method. The order page buttons appear from canCapture / canRefund. New order_refunded and order_canceled events.
PayPal was rebuilt: payment is finalized in-process on the return page (the old HTTP call to the store's own URL failed behind a bot challenge or proxy), a verified webhook at POST /api/paypal/webhook (set the webhook ID in the PayPal settings or in system.paypal.webhookId), admin refunds with partial-refund tracking, paypal_pending for pending captures, idempotent transaction recording, current Orders v2 payloads with exact-amount breakdowns (including zero-decimal currencies), and a reconciliation cron (every 30 minutes, system.paypal.abandonedOrderTtlHours, default 6) that captures approved orders and cancels and restocks abandoned ones. When a buyer cancels at PayPal, the abandoned order is now cancelled and restocked before the cart is reactivated.
Stripe: the charge amount and currency come from the order instead of the browser, the webhook verifies them, locks the order row and handles payment_intent.payment_failed and charge.refunded.
Cash on Delivery is wired into the same contract with its own cod_* statuses.
Order status changes are clamped instead of throwing on terminal or reverted states; shipments can be cancelled on refunded orders and cannot be created on terminal ones.

Transactional emails

A shared layout (header and logo, content, footer; button, divider and items-table partials; a {{t}} translation helper) now renders the order confirmation, welcome, reset password, shipment created and shipment delivered emails.
New emails: refund and cancellation, each switchable with notification_emails.order_refunded / order_canceled (enabled, templatePath).
The email copy is translated into all 17 languages (machine-assisted; less common languages deserve a native-speaker review).

Media library and file browser

The file browser is paginated for every storage provider (local, S3, Azure Blob, Google Cloud Storage) with cursors, so a folder with thousands of files no longer loads at once. Folders always load completely; listings now include size and type.
Rename files (extension is preserved, an existing name is never overwritten), paste-to-upload, a details panel with the full URL, size and dimensions, loading skeletons, and a working scrollbar. A Media library entry joins the CMS menu.
The configured upload types (System Setting → File Uploads: PDF, video, audio) are honoured by the browser; before, only images worked.

Storefront and catalog

All products page at /products, editable in the page builder, with sorting, filters, pagination, a category tree facet and an attribute facet. Included in the sitemap and offered in the link picker. The category filter now matches the whole subtree.
Virtual collections ("newest", "on sale", a category's products) for widgets and the page builder, so a new store's shelves are not empty.
Product cards decide Add to Cart themselves: simple products get the button ("Sold out" when out of stock), products with variants get Select options, a link to the product page. The featured items, recommendation, collection spotlight and rich-text product widgets gain the button.
Contact form widget with stored submissions: submissions are saved before the email is attempted, with an admin grid (unread / read / spam) and delete. The email outcome is recorded.
Admin → landing pages: Replace homepage with a landing page, with an automatic disabled backup and a one-click restore.
New featured blogs fallback (newest posts when none are picked), a slideshow placeholder in the page builder, and the page builder shows a loading skeleton while a replaced image renders.

Theme development

themes/<id>/layouts.json moves any storefront page component to another Area or sort order without forking the file. Hot reload in development; admin pages are never affected.
Theme theme.json can now ship landing pages, upload assets through the store's configured storage provider (theme-asset:<path> tokens) and reference products or collections by a stable key (store-ref:<entity>/<by>/<key>).
Shared widget classes evershop-widget__eyebrow, __heading, __subtext and __item-heading let one rule restyle every widget; vertical spacing is consistent. The Section widget follows the page column through --page-max-width and --page-gutter and exposes data-padding.
evershop seed is re-runnable and theme-aware: widgets (--widgets), variant groups, category images and a theme's retired categories are handled idempotently, size can drive a variant like colour, and seeded images go through the configured storage provider. The footer copyright is now live (© <year> <store name>) when none is set.

Security

The fixes released in v2.2.2 are listed under that version. This release also fixes:

A PayPal capture action that could be called without authentication using only an order UUID; the public PayPal capture and authorize routes were removed.
The Stripe charge amount is now derived from the order, not from client data.
?limit= on public pages could request the whole catalog in one response (denial of service).

Performance

The product listing COUNT query drops joins it does not need (about 50.7 ms → 26.5 ms on a 300,000-product catalog) and the category facet matches a subtree with one array parameter instead of a recursive subquery (about 79 ms → 2.5 ms). The store-wide attribute facet uses an EXISTS probe (about 48 ms → 2 ms on 1.2 million index rows).
Rich text sanitizing no longer bundles sanitize-html into the storefront: about 200 KB less minified (67 KB gzipped).
Image and static-asset requests no longer create a session or send a Set-Cookie, so CDNs can cache product images.

Bug Fixes

The order confirmation email no longer prefixes the base URL onto absolute (S3 and other remote) thumbnail URLs.
og:image URLs are correct for cloud storage.
Requests no longer hang when NODE_ENV is neither development nor production, and local extensions no longer vanish in that case.
A widget with settings its GraphQL type does not accept no longer takes the whole page down with a 500: unknown keys are dropped with a warning, an unusable widget is left out of the page, and saving such settings is refused.
Sorting on the product listing resets the page, and the direction toggle works on the default sort.
Display locale for prices and dates comes from the active locale, not only shop.language.
Page components are imported in Area sortOrder, so the CSS cascade follows it (headings no longer lose their Tailwind base styles on the cart and checkout pages).
Menu items are keyed by their stored id (no duplicate React keys); the mobile menu stays inside the viewport; the header renders its Areas in source order (correct keyboard tab order).
Product images default to object-fit: cover, so photos are cropped rather than stretched.
Banner and slideshow buttons and headlines are legible over photographs; the split feature's vertical alignment works; call-to-action buttons share one height; either slideshow arrows field can hide the controls.
The Section widget lines up with the page column and no longer causes sideways scrolling on Windows and Linux.
The gallery slider and the variant selector work with other bundlers and with relative product URLs.
The file browser opens above the page builder, and its clicks no longer close the settings drawer.
evershop build no longer logs a database connection error (no database exists at build time).
Seeding no longer dies on the second page, re-uploads category images, or creates a category a theme meant to retire.

Developer Experience

New npm run compile:dev compiles in place without deleting dist/, so a running dev server keeps working. compile:tsc now copies the same non-source files as compile.
Jest maps @components/* to the compiled components and stubs stylesheet imports, so page components can be unit tested.
New regression tests guard failures that compile and pass CI: a comment inside export const layout, a Node built-in reachable from a React component, and an API route that reads request.body without body parsing.
@evershop/postgres-query-builder 2.1.0 adds SelectQuery.getJoins() and pruneUnreferencedLeftJoins().

Dependencies

Added: xss; jsdom (dev, for DOM component tests).
Removed: sanitize-html and @types/sanitize-html.
The multer, sharp, axios, undici and @evershop/postgres-query-builder upgrades, and the removal of cypress, shipped in v2.2.2.

Upgrade Notes

Back up your database. This release runs 6 new migrations: checkout 1.0.12, customer 1.0.5 and tax 1.0.1 (address columns, renames only), cod 1.0.0 (moves awaiting-payment COD orders to cod_pending), cms 1.5.0 (contact_submission) and webhook 1.0.0. They apply automatically on first start. After they run, do not start v2.2.1 or v2.2.2 against the database: it starts, but every address reads back empty. To go back, restore your backup. As an alternative, run scripts/address-formats/rollback-schema.sql (psql --single-transaction -f) while you redeploy the old release: it reverses the address renames and steps the checkout, customer and tax migration records back, but it does not undo the cod status change (orders that were awaiting payment stay cod_pending) or remove the new tables.
Update @evershop/evershop, reinstall dependencies, run npm run build. Use Node.js 20.9 or newer (required since v2.2.2).
Stripe: enable payment_intent.succeeded, payment_intent.amount_capturable_updated, payment_intent.payment_failed, payment_intent.canceled and charge.refunded on your webhook endpoint.
PayPal: create a webhook in the PayPal dashboard pointing at /api/paypal/webhook and save its ID in the PayPal settings. Until then the endpoint answers 503 and the reconciliation cron is the only fallback. The old paypalWebhookSecret setting is gone.
Review your shipping zones under Settings → Shipping. Provinces became regions, and Sell to countries limits which countries checkout accepts.
If you use custom SQL, extensions or a theme: update address column names and the removed types/customerAddress and lib/locale/countries imports; replace calls to the removed payment routes with POST /api/orders/:id/capture and /refunds; delete the inline pieces from forked page shells (see Breaking Changes).
Themes that depended on order-first to place the header's center Area: Areas now render left, center, right in the markup. Check your header.
Rich text is sanitized by xss; check content that relied on <br /> output or on sanitize-html being installed.