Vue.js SDK

This guide will get you all set up with our Vue.js SDK, ready to integrate pricing, payments, authentication and more into your storefront.

The Moonbase Vue.js SDK comes with a set of composables to let you easily access products & pricing, cart and authentication, customer inventory and more. It is made using TypeScript, so you will have typed models everywhere, but you can just as easily use it in your JavaScript projects.

If you want to see the SDK in use end-to-end, our Corino reference site is a complete Nuxt 4 storefront wired to the public Corino demo tenant — landing page, embedded checkout, account area, license activation, and voucher redemption. The Reference implementation section at the bottom of this page walks through what it demonstrates.

Getting started

Start by adding the package to your project:

npm install @moonbase.sh/vue --save

Then add it to your Vue.js app by passing the proper configuration:

import { createStorefront } from '@moonbase.sh/vue'
import { createApp } from 'vue'
import App from './App.vue'

const storefront = createStorefront('https://{YOUR-ACCOUNT-ID}.moonbase.sh')

createApp(App)
  .use(storefront)
  .mount('#app')

Nuxt SSR support

The Moonbase Vue.js SDK is made to also support server side rendering. To avoid state leakage and support state hydration in Nuxt, you need to replace the state factory when instantiating the storefront. The appropriate place to configure this is through a Nuxt plugin:

import { createStorefront } from '@moonbase.sh/vue'

export default defineNuxtPlugin(async (nuxtApp) => {
    const storefront = createStorefront(
        nuxtApp.$config.public.moonbaseEndpoint,
        (key, state) => useState(key, () => state),
        { persistUtm: true },
    )

    // Hydrate the catalog (and current user, if a session cookie is present)
    // into the SSR payload so the first paint already has real data.
    if (import.meta.server)
        await storefront.updateStorefront()

    // Optional: react to checkout completion in the browser — for example,
    // redirect to an order-confirmation page.
    // if (import.meta.client) {
    //     storefront.onCheckoutCompleted((order) => {
    //         navigateTo(`/order-completed?id=${order.id}`)
    //     })
    // }

    nuxtApp.vueApp.use(storefront)
})

Passing Nuxt's useState as the state factory means every reactive store the SDK owns — catalog, current user, cart and inventory — is serialized from the server into the client payload. The SDK rehydrates from that payload on the client instead of refetching, so the first paint has real prices, product names and login state.

The { persistUtm: true } option stores detected UTM parameters in localStorage (instead of the default sessionStorage), which lets attribution survive across tabs and follow a visitor all the way through to a future checkout — useful when you've set up marketing revenue tracking.

onCheckoutCompleted only fires in the browser, so register it inside an import.meta.client branch. It's the right place to send users to an order-confirmation page or trigger any post-purchase cleanup. The handler pairs naturally with the embedded checkout overlay — see useCart below.

Composables

All composables use the same core storefront context that you set up using the above instructions.

useAuth

The useAuth composable contains functions to handle user authentication, as well as a computed property of the currently logged-in user and whether the user has been loaded yet.

import { useAuth } from '@moonbase.sh/vue'

const {
    user,
    loaded,
    signIn,
    signUp,
    signOut,        // 🔒 Needs authenticated user
    update,         // 🔒 Needs authenticated user
    setPassword,    // 🔒 Needs authenticated user
    forgotPassword,
    resetPassword,
    confirmAccount, // ! Returns password reset token to set initial password
    confirmEmail,
    confirmEmailChange, // 🔒 Needs authenticated user
} = useAuth()

The SDK will try to load the user on page load, if a valid user access token is found in localStorage. Refreshing the access token is also handled by the SDK, so you don't need to worry about refreshing tokens yourself.

useInventory

The useInventory composable exposes a number of endpoints to fetch customer inventory, or in other words; what products and licenses the authenticated customer owns. To be able to build a fully self-service licensing experience, the composable also allows fetching activations for licenses, as well as revoke them on demand.

If you are using offline activations, that can also be handled using the activateProduct endpoint, which takes in a device token and returns a license token usable for offline activations. To learn more about offline activations, check out our documentation on activation flows.

import { useInventory } from '@moonbase.sh/vue'

const {
    getLicenses,
    getLicenseActivations,
    getProduct,
    getProducts,
    getProductLicenses,
    getProductActivations,
    revokeActivation,
    activateProduct,
    downloadProduct,
    getSubscription,
    getSubscriptions,
} = useInventory()

When setting up products in Moonbase, you have the ability to control who can download releases of your products, either opening it up for everyone, requiring authenticated users, or even requiring downloaders to own the software. In the case you pick anything but the first option, it's important that you use the downloadProduct method to fetch and open authenticated download links in order to avoid authentication errors for users of your storefront. On the other hand, if you don't have any authorization policy in place, you can simply redirect users to the path of the product downloads as necessary.

The getProduct method returns the full owned-product detail for a single product the customer owns — downloads, external licenses (key codes, file licenses, iLok deposits), and metadata — and is what backs a per-product page in an account area. getSubscription returns the detail for a single subscription and is the handler for the ManageSubscription callback URL (see Custom storefront mode).

useActivationRequest

The useActivationRequest composable wraps an in-progress activation request, identified by a token. Moonbase issues these tokens to the AutoActivation custom-storefront URL when a customer kicks off an online activation from inside your application — either to redeem an offer (a paid license) or to start a free trial. The composable resolves the token to the underlying request, exposes eligibility and loading state, and returns methods to complete or abandon the flow.

import { useActivationRequest } from '@moonbase.sh/vue'

const {
    activationRequest, // computed ref of the loaded ActivationRequest
    loading,           // initial token resolve in progress
    fulfilling,        // a fulfill call is currently running
    completing,        // post-fulfill polling for the license to land
    error,             // user-facing error message, if any
    isInstalled,       // true once the resulting license is provisioned
    fulfillLicense,    // complete the request by purchasing / claiming the license
    fulfillTrial,      // complete the request by starting a free trial
    cancel,            // abandon the request server-side
} = useActivationRequest(token)

Typical usage is on an /activate page that reads ?token=… from the URL: pass the token to useActivationRequest, render the product and pricing from activationRequest.value, and wire two buttons to fulfillLicense() and fulfillTrial(newsletterOptIn) based on what the request is eligible for. After fulfillLicense(), the SDK opens the embedded checkout overlay for payment; after fulfillTrial(), the license is provisioned directly. In both cases isInstalled flips to true once the license has been delivered to the user.

For a deeper look at the activation flow this composable participates in, see activation flows. For a working /activate page, see activation/AutoActivation.vue in the Corino reference site.

useBundle

The useBundle composable returns a computed ref of a specific bundle specified by the bundle ID given.

import { useBundle } from '@moonbase.sh/vue'

const bundle = useBundle('demo-bundle')

The bundle will be null if it's not found in your publicly available bundles, or if the storefront data has not yet been loaded.

useBundles

The useBundles composable returns a computed ref of all currently loaded and available bundles.

import { useBundles } from '@moonbase.sh/vue'

const bundles = useBundles()

The bundle list will be empty if the storefront data has not yet been loaded.

useProduct

The useProduct composable returns a computed ref of a specific product specified by the product ID given.

import { useProduct } from '@moonbase.sh/vue'

const product = useProduct('demo-product')

The product will be null if it's not found in your publicly available products, or if the storefront data has not yet been loaded.

useProducts

The useProducts composable returns a computed ref of all currently loaded and available products.

import { useProducts } from '@moonbase.sh/vue'

const products = useProducts()

The product list will be empty if the storefront data has not yet been loaded.

useOffer

The useOffer composable returns a computed ref of a specific offer specified by the offer ID given.

import { useOffer } from '@moonbase.sh/vue'

const offer = useOffer('d6688961-7843-4bf4-be7c-4d9d6c5ce7be')

The offer will be null if it's not found, or if the storefront data has not yet been loaded.

useOffers

The useOffers and useEligibleOffers composables returns a computed ref of all offers and eligible offers respectively. Eligible offers are offers where the condition of the offer is currently satisfied, and the promoted product is not already in the cart.

import { useOffers, useEligibleOffers } from '@moonbase.sh/vue'

const offers = useOffers()
const eligibleOffers = useEligibleOffers()

These lists will be empty if the storefront data has not yet been loaded.

useCart

The useCart composable contains functions to handle cart manipulation, as well as a computed property of the current contents and value of the cart. To avoid delays in rendering, the total of the cart contents is calculated client-side based on products added to the cart.

import { useCart } from '@moonbase.sh/vue'

const {
    items,
    currency,
    total,
    addToCart,
    setQuantity,
    removeFromCart,
    checkout,
} = useCart()

The SDK takes care of storing the cart session in browser storage so that customers can resume shopping when coming back to the store. Also handled by the SDK is shopping in multiple tabs simultaneously, where the cart will be kept synchronized across the tabs.

Calling checkout({ redirect: true }) redirects the user to a hosted Moonbase checkout page, after which they are redirected back to the configured return URL.

Passing redirect: false instead opens the checkout as an embedded overlay in the current page — no navigation, no full-page reload. This is what the Corino reference site uses from its right-side cart drawer:

const cart = useCart()
const route = useRoute()

async function startCheckout() {
    await cart.checkout({ redirect: false, returnUrl: route.path })
}

Pair the overlay with the onCheckoutCompleted and closeCheckout handlers exposed by createStorefront (see Nuxt SSR support) — register an onCheckoutCompleted listener at boot to close the overlay and dismiss your cart drawer once an order completes. The returnUrl is still used by any flows the backend wants to resume on the storefront side (e.g. confirming an order email).

useVoucher

The useVoucher composable contains functions to handle voucher redemption. Vouchers are redeemable codes that grant licenses to products on redemption. Since these are redemeed to a customer, redeeming a voucher will require an authenticated user. See the useAuth composable for how to authenticate customers.

import { useVoucher } from '@moonbase.sh/vue'

const {
    peek,
    redeem, // 🔒 Needs authenticated user
} = useVoucher()

The returned payload from these methods contain details on which products and bundles have been redeemed by the voucher.

Custom storefront mode

A tenant configured for custom storefront mode drives users back to merchant-controlled URLs for the flows Moonbase normally handles on its own hosted customer portal — license activation, sign-in callbacks, email confirmations, password resets, product downloads, and subscription management. Each entry in the tenant's CustomStorefrontLocations settings maps to a path on your storefront origin; the backend appends the listed query parameters and redirects the user there.

When you build a custom storefront on this SDK, you implement one page per row in the table below. Pick the SDK call from the right-hand column and feed it the query params from the URL.

The paths are suggestions — the only requirement is that whatever path you configure on the tenant matches the route you implement. For working implementations of every row above, see the Corino reference site below.

Reference implementation: Corino

For a complete, end-to-end example of the Vue SDK powering a real custom storefront, see the open-source Corino reference site — a Nuxt 4 build for a fictional Oslo audio-plugin company wired to the public corino-demo.moonbase.sh tenant. It exists specifically as a demonstration of what it takes to ship a custom storefront on this SDK: marketing landing page, cart drawer, embedded checkout, account area, product downloads, license activation, and voucher redemption — with the catalog and user state hydrated into the SSR payload so the first paint is real data.

Try it live at corino-vue.moonbase.sh — sign up with any email, add a plugin to your cart, and walk through the embedded checkout against the demo tenant. Then read the source — the repo shows how to wire every composable on this page into a working storefront:

• SSR plugin boot (app/plugins/moonbase.ts) with the useState factory, { persistUtm: true }, server-side await updateStorefront(), and a browser-only onCheckoutCompleted cleanup.
• Live-bound pricing and ownership-aware CTAs via useProduct / useBundle in PluginCard.vue and BundleSection.vue — the same card swaps its "Add to cart" button for "Download" once the user owns the product.
• Embedded checkout overlay opened from a right-side cart drawer (CartDrawer.vue) via cart.checkout({ redirect: false }) and torn down via onCheckoutCompleted + closeCheckout.
• Account area at /account with nested routes for profile (useAuth().update / setPassword / signOut), owned products (useInventory().getProducts), per-product downloads and activations (getProduct, downloadProduct, getProductActivations, revokeActivation, getProductLicenses), and voucher redemption (useVoucher().redeem).
• License activation at /activate covering both modes — the online ?token= flow via useActivationRequest(token), and the offline machine-file upload via useInventory().activateProduct(token, ActivationMethod.Offline), which returns a data: URL for the resulting license file.
• Custom-storefront callback pages for every row in the table above — /login, /sign-up, /confirm-email, /forgot-password (request + reset modes), /download, /subscriptions, and /account/confirm-email-change.
• Deep-link auto-add-to-cart via ?add_product=… / ?add_bundle=… handled in app.vue, so marketing links can drop visitors straight into the cart drawer.

If you want a much smaller integration with no build step, the embedded storefront docs cover a separate single-file HTML reference site for the same fictional shop.