Lemon Squeezy
Lemon Squeezy is a merchant-of-record platform for digital products and subscriptions.
Use useScriptLemonSqueezy() for Lemon.js calls. <ScriptLemonSqueezy> turns checkout links into overlay triggers.
Nuxt Config Setup
Add this to your nuxt.config.ts to load Lemon Squeezy globally. Alternatively you can use the useScriptLemonSqueezy composable for more control.
export default defineNuxtConfig({
scripts: {
registry: {
lemonSqueezy: {
trigger: 'onNuxtReady',
}
}
}
})This config automatically enables first-party mode (proxy). See below to customise.
useScriptLemonSqueezy()
The useScriptLemonSqueezy composable lets you have fine-grain control over when and how Lemon Squeezy is loaded on your site.
const { proxy } = useScriptLemonSqueezy()
proxy.LemonSqueezy.Setup({ eventHandler })Please follow the Registry Scripts guide to learn more about advanced usage.
First-Party Mode: Privacy Focused Proxy
No extra config needed. Runtime requests are reverse-proxied through your server instead of going directly to Lemon Squeezy. User IPs are anonymised and requests work with ad blockers. Learn more.
export default defineNuxtConfig({
scripts: {
// ✅ First-party mode: proxied
registry: {
lemonSqueezy: {
trigger: 'onNuxtReady',
},
},
},
})Example
Using Lemon Squeezy in a component with the proxy to send events .
<script setup lang="ts">
const { proxy } = useScriptLemonSqueezy()
// noop in development, ssr
// just works in production, client
function handleAction() {
proxy.LemonSqueezy.Setup({ eventHandler })
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template><ScriptLemonSqueezy>
The headless facade component scans the links present when it mounts. It loads Lemon.js when the component's root enters the viewport.
<template>
<ScriptLemonSqueezy>
<NuxtLink href="https://harlantest.lemonsqueezy.com/buy/52a40427-36d2-4450-a514-ae80d9e1a333?embed=1">
Buy me for $9.99
</NuxtLink>
</ScriptLemonSqueezy>
</template>
At mount, it adds the .lemonsqueezy-button class to links inside the component. Links inserted later are not scanned. Add the class yourself and call Refresh(), or remount the component, after adding a checkout link dynamically.
Demo
Component API
See the Facade Component API for full props, events, and slots.
Events
lemon-squeezy-event
The component forwards Lemon.js overlay events through this event. The payload contains an event name and, for events such as Checkout.Success, a data object.
LemonSqueezyEventPayload TypeScript definition intersects mutually exclusive event names and can reduce the payload to never. Until the type changes, accept unknown at your handler boundary and narrow it to the fields you use.useScriptLemonSqueezy()
Use useScriptLemonSqueezy() when you need Lemon.js without the checkout-link component.
export function useScriptLemonSqueezy<T extends LemonSqueezyApi>(_options?: LemonSqueezyInput) {}
See Registry Scripts for trigger and loading options.
If you use the composable without the component and add checkout links after Lemon.js loads, call Refresh() so the SDK attaches overlay listeners to the new links:
proxy.Refresh()
export type LemonSqueezyEventPayload = { event: 'Checkout.Success', data: Record<string, any> }
& { event: 'Checkout.ViewCart', data: Record<string, any> }
& { event: 'GA.ViewCart', data: Record<string, any> }
& { event: 'PaymentMethodUpdate.Mounted' }
& { event: 'PaymentMethodUpdate.Closed' }
& { event: 'PaymentMethodUpdate.Updated' }
& { event: string }Example
Initialize Lemon.js for a payment link:
<script setup lang="ts">
const { proxy } = useScriptLemonSqueezy()
proxy.Setup({
eventHandler(event) {
console.log(event)
},
})
</script>
<template>
<a href="https://harlantest.lemonsqueezy.com/buy/52a40427-36d2-4450-a514-ae80d9e1a333?embed=1" class="lemonsqueezy-button">Buy now</a>
</template>