Installed SDK integration guides
Shared rules for integrating a saved Lockerverse resource into an existing website.
Required quality and upgrade instructions
Read node_modules/@lockerverse/react/SDK_RULES.md before implementation.
Follow its host-instruction section to create or merge the short SDK maintenance
rule in the host root AGENTS.md, preserving unrelated instructions. This is
required for both new integrations and updates; report if it cannot be saved.
Before an upgrade, record the resolved installed versions. After installing the
target pair, read node_modules/@lockerverse/react/MIGRATIONS.md and apply all
applicable entries between the old and target versions in order. Review the
existing-integration baseline when the host has not used this guide before.
Report applied steps, skipped steps with reasons, and verification limits.
Changing only the dependency version does not complete an upgrade. Core-only
consumers use the same files in node_modules/@lockerverse/sdk/.
Read the installed contract first
For an installed project, read node_modules/@lockerverse/react/guides/integration.md
and the guide for the requested resource:
node_modules/@lockerverse/react/guides/auctions.mdnode_modules/@lockerverse/react/guides/payment-widgets.mdnode_modules/@lockerverse/react/guides/events.mdnode_modules/@lockerverse/react/guides/signup.md
These files ship with each release. Their contract matches that installed
release. Also read its README.md, package.json exports, peer dependencies,
and public .d.ts declarations. Do not import private dist modules. Online
examples can describe a newer release. These guides are generated from the same
maintained documentation as the website; do not edit generated guide copies.
Install or upgrade without downgrading
Inspect the package manager, lockfile, and installed versions first. Treat a
version in the admin prompt as the minimum supported stable release, not a
request to replace an existing newer release. Keep @lockerverse/react and
@lockerverse/sdk on the same exact stable version. If both are already on a
newer matching stable version, keep them and read their installed guides. If the
pair is missing, older, mismatched, or lacks the required guide, select a
published matching stable release that meets the prompt minimum and is not
older than either installed stable package. Verify that both versions exist
before installing. Do not choose a development dist-tag or downgrade a package.
Use the existing package manager and update its lockfile.
Keep compatible React and React DOM versions. The current SDK supports
^18.2.0 || ^19.2.0; check the selected release’s manifest. Do not upgrade a
compatible React 18 site to React 19. If an upgrade is needed, update React and
React DOM together without replacing the framework or router. Native payment
and auction checkout need the optional @stripe/react-stripe-js and
@stripe/stripe-js peers specified by the installed manifest. Catalog, Events,
and signup code must use their narrow imports and must not load Stripe.
Preserve the existing host and saved resource
Use the existing framework, router, page structure, components, and theme.
Connect the matching existing section and controls. Add one section only when
none exists. Do not create a second application, backend, router, or duplicate
interface. Change only files needed for this integration; do not edit generated
route trees. Match light/dark theme to the host and use supported props and
--lockerverse-* tokens with complete valid CSS values. Do not override private
SDK selectors or rebuild the supplied auction, checkout, or signup controls.
The admin prompt supplies public resource identity and requested behavior. Load current settings from Lockerverse on each page load or refresh. Do not copy item names, prices, order, images, dates, quantities, availability, fees, shipping rules, or form definitions into permanent local configuration. Use only the requested community and saved resource. Encode route values and keep host search parameters. A URL must not select a different configured community or resource. A mounted hook keeps one identity; remount deliberately when the resource changes, never during an unresolved submission.
Use the supplied apiBaseUrl and environment exactly. API base URLs include
/api. Production is the default when neither is supplied. Do not infer the
environment from the host domain or silently use development. Lockerverse
supplies Stripe publishable keys and connected-account options. Do not add
secret keys, an unrelated Stripe account, Supabase payment tables, guessed
endpoints, or an independent payment flow.
Server rendering and static sites
On an existing SSR host, load public data with the matching SDK client in the framework’s server route or server function. Seed the matching React hook and keep available content visible during refresh. Render public text, images, links, and metadata in the first HTTP response. Keep Stripe initialization and browser-storage access in the browser. Use the product guide for exact seed arguments and loading behavior.
On an existing static Vite site, preserve its client-loaded flow. Explain that current item-specific first-response content and metadata require an SSR response or another static build. Do not add a per-site server or replace the framework solely for this integration. A browser-only title change is not server-rendered metadata. The host owns canonical URLs, document metadata, sitemaps, robots rules, and its indexing policy.
Private data and submission state
Never put contact details, payment tokens, or recovery records in URLs, public loader data, metadata, analytics, or logs. Use public read data only in SSR responses. Do not submit live payments, bids, or signup records during an implementation check. Use the product’s completion callback as documented; navigation, dialog closure, and receipt amounts are not proof of payment.
Payment-widget recovery and auction recovery have different contracts. Payment widget recovery contains a payment reference and connected account and can be stored as specified in its guide. Auction purchase recovery includes buyer data and a Stripe token: keep it private and in memory by default. Do not persist it merely because widget recovery can be persisted. Never replace an unresolved operation with a fresh payment or automatically retry an uncertain bid.
Verify the integration
Build with the host’s existing commands. Check desktop and 390 by 844 mobile layouts for overflow, readable content, and reachable controls. Check loading, empty, error, retry, unavailable, and ready states as applicable. Check route direct entry, reload, Back/Forward, and native new-tab links. For SSR, inspect the raw first HTTP response, then check hydration and live refresh. Open checkout only to inspect saved settings; do not submit a transaction. Use SDK simulation pages for result layouts. Report verified checks and any limits.