Welcome to @planship/nuxt
, a Nuxt module that enables entitlements, metering, plan packaging, and customer/subscription management in your Nuxt app powered by Planship. This module is based on the @planship/vue
plugin and @planship/fetch
library.
A complete, working example of a Nuxt app that uses this module can be found at https://github.com/planship/planship-nuxt-example.
Install @planship/nuxt
with npm, yarn or pnpm:
npm install @planship/nuxt
# or
yarn add @planship/nuxt
# or
pnpm add @planship/nuxt
Then, add @planship/nuxt
to the modules
section of your nuxt.config.ts
:
export default defineNuxtConfig({
modules: ['@planship/nuxt']
})
Finally, configure your Planship product slug and authentication credentials inside defineNuxtConfig
or via environment variables.
export default defineNuxtConfig({
// ...
planship: {
productSlug: '<YOUR_PLANSHIP_PRODUCT_SLUG',
clientId: '<YOUR_PLANSHIP_API_CLIENT_ID>',
clientSecret: '<YOUR_PLANSHIP_API_CLIENT_SECRET>'
}
}
productSlug
Your Planship product slug. The slug can be also defined via the PLANSHIP_PRODUCT_SLUG
environment variable.
clientId
and clientSecret
Your Planship authentication credentials. They can be also defined via the PLANSHIP_API_CLIENT_ID
and PLANSHIP_API_CLIENT_SECRET
environment variables.
The @planship/nuxt
module exports two composables implemented by the @planship/vue
plugin: usePlanshipCustomer
and usePlanship
. The @planship/vue
plugin is universal-mode friendly, meaning that these composables can be used for both server-side and client-side rendering.
In most rendering scenarios, your app will need to fetch and evaluate Planship entitlements for a specific customer. This can be accomplished with the Planship plugin and the usePlanshipCustomer
function, which initializes a Planship API instance for a specific customer, continously fetches their entitlements
, and exposes them in a reactive Vue ref object.
The example below shows how customer entitlements are retrieved, and a simple boolean feature called advanced-analytics
is used to conditionally render a <NuxtLink>
element inside a Vue component.
<script setup>
import { usePlanshipCustomer } from '@planship/nuxt'
const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')
</script>
<template>
<NuxtLink
v-if="entitlements['advanced-analytics']"
to="/analytics"
>
Analytics
</NuxtLink>
</template>
When usePlanshipCustomer
is used on the client-side, entitlements are automatically updated via a WebSocket connection every time they change.
When used in the universal rendering mode, the data is fetched in the following fashion:
- The plugin is initialized on the server and Planship entitlements and subscription data are fetched so they can be used for server-side rendering.
- The plugin is initialized on the client using the data already fetched on the server.
- The pluging re-hydrates itself on the client and initiates a websocket connection for continuous entitlements updates from Planship.
The usePlanshipCustomer
function returns a composite result that is both a promise and a data object the promise resolves to. This means that the function can be called both as a synchronous function or an asynchronous one using await
(or then/catch
chain).
If you want to block code execution until customer entitlements are fetched from the Planship API, call the function with await
:
const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')
If you want to return immediately and fetch entitlements asynchronously, simply call usePlanshipCustomer without await
:
const { entitlements } = usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')
Since entitlements
is a reactive Vue Ref object, you can use it in your component and page templates and let Nuxt automatically rerender once the entitlements are fetched.
Your app may need to fetch additional customer data from Planship (E.g. customer subscription or usage data). To accomplish any Planship API operation use an instance of the Planship Customer API client returned by the usePlanshipCustomer
function.
Below is an example Nuxt setup script that retrieves a list of subscriptions for the current customer using Nuxt's useAsyncData
.
<script setup>
import { usePlanshipCustomer } from '@planship/nuxt'
const { planshipCustomerApiClient } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>')
const { data: subscriptions } = await useAsyncData('subscriptions', async () => {
return await planshipCustomerApiClient.listSubscriptions()
})
</script>
When working with the entitlements dictionary returned by usePlanshipCustomer
, it can be useful to wrap it in an object with getters for individual levers. This is especially advantageous in IDEs like VS Code where it enables autocomplete for entitlements
.
To accomplish this, define an entitlements class for your product and pass it to usePlanshipCustomer
.
<script setup>
import { usePlanshipCustomer, EntitlementsBase } from '@planship/nuxt'
class MyEntitlements extends EntitlementsBase {
get apiCallsPerMonth(): number {
return this.entitlementsDict?.['api-calls-per-month'].valueOf()
}
get advancedAnalytics(): boolean {
return this.entitlementsDict?.['advanced-analytics']
}
}
// entitlements is of Ref<MyEntitlements> type
const { entitlements } = await usePlanshipCustomer('<CURRENT_CUSTOMER_ID>', MyEntitlements)
</script>
<template>
<NuxtLink
v-if="entitlements.advancedAnalytics"
to="/analytics"
>
Analytics
</NuxtLink>
</template>
If the current customer context is unknown, the usePlanship
function can retrieve a Planship API client. It exposes the same functionality as the Planship customer API client provided by usePlanshipCustomer
, but all customer operations (E.g. fetching entitlements and subscriptions) require a Planship customer ID as an argument.
Below is an example Nuxt setup script that retrieves a list of Planship plans using Nuxt's useAsyncData
.
<script setup>
import { usePlanship } from '@planship/nuxt'
const { planshipApiClient } = usePlanship()
const { data: plans } = await useAsyncData('plans', async () => {
return await planshipApiClient.listPlans()
})
</script>
Since usePlanshipCustomer
and usePlanship
composables use the Vue provide/inject mechanism, they can be used in application components only. To simplify consuming Planship data outside of component code (E.g. server routes), the @planship/nuxt
module provides the useServerApiClient
server service available within the #planship/server
alias.
Below is the example of a Nuxt API endpoint that reports metered usage to the Planship API using a Planship API client retrieved via the useServerApiClient
server service function.
import { useServerApiClient } from '#planship/server'
export default defineEventHandler(async (event) => {
const planship = useServerApiClient()
const body = await readBody(event)
// Report usage for api-call metering ID to Planship
return planship.reportUsage(body.userId, 'api-call', body.count)
})