--- title: Installed SDK integration guides description: Shared rules for integrating a saved Lockerverse resource into an existing website. sidebar: order: 2 --- ## 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.md` - `node_modules/@lockerverse/react/guides/payment-widgets.md` - `node_modules/@lockerverse/react/guides/events.md` - `node_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.