@reactivlabs/referly
v0.1.1
Published
Drop-in React provider, hook, and modal for offering Referly partner referrals on any site.
Maintainers
thereactivlabsReadme
@reactivlabs/referly
Drop-in React provider, hook, and modal for offering Referly partner referrals after a form submission on any React or Next.js site.
- Zero runtime dependencies (besides React itself)
- First-class Next.js App Router support — the built bundle ships with
"use client"baked in - ESM + CJS output, full TypeScript types
- Inline styles — works on any site, no CSS imports required
Install
npm install @reactivlabs/referly
# or
pnpm add @reactivlabs/referly
# or
yarn add @reactivlabs/referlyPeer dep: react >= 18.
Quick start
Get a partner API key from Referly → Dashboard → Integrations → Generate, then:
// app/layout.tsx
import { ReferlyProvider } from "@reactivlabs/referly";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<ReferlyProvider
partnerKey={process.env.NEXT_PUBLIC_REFERLY_PARTNER_KEY!}
apiBase="https://referly.yourdomain.com"
>
{children}
</ReferlyProvider>
</body>
</html>
);
}"use client";
import { useReferly } from "@reactivlabs/referly";
export function ContactForm() {
const { offerPartners } = useReferly();
async function onSubmit(values: { name: string; email: string; phone: string; service?: string }) {
await saveToYourBackend(values);
offerPartners({
customer: {
name: values.name,
email: values.email,
phone: values.phone,
},
service: values.service ?? "general",
});
}
// render your form and wire `onSubmit`…
}API
<ReferlyProvider> props
| Prop | Type | Description |
| --- | --- | --- |
| partnerKey | string | Per-member key from Dashboard → Integrations. Looks like rly_live_.... Treat like a password. |
| apiBase | string | Origin of the Referly deployment (e.g. https://referly.yourdomain.com). |
| onReferralRecorded? | (partner, action) => void | Fires after a successful click on Get info or Send info. |
useReferly().offerPartners(args)
offerPartners({
customer: { name: string; email?: string; phone?: string };
service?: string;
notes?: string;
heading?: string; // custom modal title
subheading?: string; // custom modal subtitle
hpCompany?: string; // honeypot pass-through (optional)
});Opens the modal, fetches the site owner's partner list, lets the customer pick. Two click-through actions:
- Get info — partner follows up with the customer
- Send info — partner gets notified AND the customer is emailed the partner's contact info
Internal partners (other Referly members in the same group) land in their dashboard. External partners create a row in the owner's integrations activity feed and get a notification email if you provided one.
Full integration guide
See the long-form guide (WordPress, Wix, Webflow, Squarespace, Shopify, plain HTML, cURL, endpoint reference, security): referly.app/docs/partner-integration
Development
# from this directory (referly/embed)
npm install
npm run build # → dist/{index.js,index.cjs,index.d.ts}
npm run dev # rebuild on savePublishing
This package is published separately from the main Referly app. Only the dist/, README.md, and LICENSE files are shipped (see the files field in package.json).
One-time setup:
- Make sure the
@reactivlabsscope exists on npm and you're a member: https://www.npmjs.com/org/reactivlabs npm login(must be a user with publish rights on the org).
For each release:
# from referly/embed
npm version patch # or minor / major — bumps package.json + creates a git tag
npm publish # runs prepublishOnly → npm run build, then uploads
git push --follow-tagsThe first publish needs --access=public (the publishConfig in package.json already sets this).
License
MIT