Nudgekit guide
Nudgekit adds six conversion blocks to your storefront: product labels and badges, countdown timers, an announcement bar, a free-shipping progress bar, a sticky add-to-cart bar and trust badges. You configure them from the BigCommerce control panel.
- Stencil themes (Cornerstone and the themes built on it): nothing to install. Switch the channel on and Nudgekit adds itself to every page.
- Catalyst storefronts: a developer adds the
@medusa-it/nudgekitpackage once. The blocks are React Server Components that render with the page (no flash, no layout shift).
1. Install the app and pick a channel
Install Nudgekit from the App Marketplace. Every setting belongs to a channel (storefront): choose it with the selector at the top of each tab. The first Catalyst channel (or, without one, the first Stencil channel) is switched on at install; switch others on in Setup (the Plus plan allows up to 5).
2a. Stencil: nothing to install
When a Stencil channel is switched on, Nudgekit adds a script to it through BigCommerce's Scripts API (it is removed when you switch the channel off or uninstall the app). The blocks then appear where Cornerstone has room for them: badges on product images and above the product title, the countdown under the price and under category and cart titles, the announcement bar at the top, the free-shipping bar on the cart page, trust badges under add to cart, in the cart and in the footer. Badge rules read prices, stock and categories through your theme's Storefront API token.
A custom theme that places things differently can say where each block goes with an empty placeholder in its templates (Storefront › Themes › Advanced › Edit theme files):
<div data-nudgekit-slot="announcement"></div>
<div data-nudgekit-slot="countdown"></div>
<div data-nudgekit-slot="badges-pdp"></div>
<div data-nudgekit-slot="trust-atc"></div> <!-- also trust-cart, trust-footer -->
<div data-nudgekit-slot="shipping-bar"></div>
<div class="card-figure" data-nudgekit-card="{{id}}">…</div> <!-- product card image box -->
Changes saved in the app show on the storefront within a few minutes.
2b. Catalyst: add the package (a developer, once)
The Setup tab shows these snippets with your own keys.
pnpm add @medusa-it/nudgekit
Environment variables (Vercel project settings, or .env.local):
BIGCOMMERCE_CHANNEL_ID=… # Catalyst already has it
BLOCKS_PUBLIC_KEY=nk_pub_… # Setup tab
NUDGEKIT_API_URL=https://nudgekit.medusa-it.app
NUDGEKIT_REVALIDATE_SECRET=nk_rev_… # Setup tab, for instant updates
Wrap the storefront in the provider, in core/app/[locale]/(default)/layout.tsx:
import { AnnouncementBar, BlocksProvider } from '@medusa-it/nudgekit';
<BlocksProvider>
<AnnouncementBar locale={locale} />
<Header />
{children}
</BlocksProvider>
Then put the blocks where you want them:
| Block | Component | Where |
|---|---|---|
| Badges | <ProductBadges product={product} placement="card" /> | Inside the product card's image box (make it position: relative), and with placement="pdp" on the product page. |
| Countdown | <Countdown page="product" productId={…} categoryIds={…} /> | Product page, category page (page="category"), cart (page="cart"), or id="…" for one timer. |
| Announcement bar | <AnnouncementBar locale={locale} customerGroupId={…} /> | Top of the layout. |
| Free-shipping bar | <ShippingBar cart={…} /> | Cart page or drawer. Mount the cart route (below) so it follows the cart. |
| Sticky add-to-cart | <StickyAddToCart name={…} price={…} imageUrl={…} /> | Product page. Add data-blocks-product-form to the add-to-cart <form>. |
| Trust badges | <TrustBadges placement="atc" /> | Under the add-to-cart button, "footer" or "cart". |
Instant updates after a save, and the cart for the free-shipping bar, are two small routes:
// core/app/api/nudgekit/revalidate/route.ts
import { createRevalidateRoute } from '@medusa-it/nudgekit/next';
export const { POST } = createRevalidateRoute();
// core/app/api/nudgekit/cart/route.ts
import { createCartRoute } from '@medusa-it/nudgekit/next';
export const { GET } = createCartRoute(async () => { /* read the cart, return { subtotal, currency, itemCount } */ });
Enter the revalidate route's URL in Setup and click Send test revalidate. Without it, changes show within a minute.
Makeswift: register the blocks next to Catalyst's own in core/lib/makeswift/components.ts:
import { registerNudgekitComponents } from '@medusa-it/nudgekit/makeswift';
import { runtime } from './runtime';
registerNudgekitComponents(runtime);
3. Configure the blocks
- Badges: rules with conditions (category, brand, price, discount, stock, new arrivals, custom field, product list, free shipping, pre-order) combined with AND / OR. Drag rules to order them; when two badges want the same corner, the higher priority wins. Test against product runs the rules on a real product.
- Timers: a fixed end date, every day at a time (store timezone), evergreen (N hours from each shopper's first view) or the end date of a BigCommerce promotion. Use
{days} {hours} {mins} {secs}in the message. - Announcement: up to 5 rotating messages, each with a link, dates, and targeting by page path, customer group, language and device.
- Shipping bar: the free-shipping amount per currency, optionally per country or customer group, and a second free-gift tier.
- Sticky ATC and Trust: position, devices, colours; payment marks are read from your store's payment methods.
Colours left empty follow your Catalyst theme (--primary, --foreground, --background, --contrast-*). Override any of them with the --nk-* CSS variables.
Plans
| Free | Growth | Plus | |
|---|---|---|---|
| Blocks | Badges, trust badges | All six | All six |
| Channels | 1 | 1 | Up to 5 |
| Badge rules | 3 | Unlimited | Unlimited |
| Scheduling, customer-group targeting | – | – | ✓ |
| “Powered by Nudgekit” link | Shown | Shown | Removed |
Subscribe or change plan in Billing; the charge appears on your BigCommerce invoice. Uninstalling cancels the subscription.
Questions? See Support.