A Nuxt 3/4 module for integrating Stripe

With this Nuxt module you can use Stripe easily in your client or server side. Use useServerStripe(event) in your server routes and useClientStripe() on the client. @stripe/stripe-js is optional and only needed if you want to use client-side features of Stripe.

Release Notes - Online playground

Features

• Server-side Stripe via useServerStripe(event) — singleton per request context
• Client-side Stripe via useClientStripe() — wraps loadStripe with auto-load or manual mode
• Runtime config support — configure via module options or runtimeConfig
• TypeScript first — full types for both server and client
• Nuxt 3 and 4 compatible — Minimum Nuxt version is 3.1.0

TypeScript

All Stripe types are re-exported directly from this module. No need to import from stripe or @stripe/stripe-js separately:

import type { ServerStripe, Stripe, StripeElements } from '@shooteger/nuxt-stripe'

| Type | Source | Description | | --- | --- | --- | | ServerStripe | stripe | Server-side Stripe instance (aliased to avoid collision with client Stripe) | | Stripe | @stripe/stripe-js | Client-side Stripe.js instance | | StripeElements | @stripe/stripe-js | Stripe Elements container | | StripeElement | @stripe/stripe-js | Individual Stripe Element | | StripePaymentElement | @stripe/stripe-js | Payment Element specifically |

Installation

One of the changes over the original fork is, that this module uses stripe packages as peer dependencies, which gives you full control over which Stripe versions you use and avoids duplicate instances in your project.

# Server + client side (Stripe Elements, client-side UI)
npm install @shooteger/nuxt-stripe stripe @stripe/stripe-js

# Server side only (webhooks, payment intents, checkout sessions, ...)
npm install @shooteger/nuxt-stripe stripe

Peer dependency versions: Both stripe and @stripe/stripe-js are peer dependencies — you control which versions you use and avoid duplicate instances in your project. stripe >= 17.0.0 and @stripe/stripe-js >= 5.0.0 are supported. @stripe/stripe-js is fully optional and only needed for client-side usage.

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@shooteger/nuxt-stripe"],
});

Configuration

Environment Variables

The recommended way to configure keys is via environment variables:

NUXT_STRIPE_SECRET_KEY=sk_test_...
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

Nuxt picks these up automatically via its runtime config convention.

Via module options

export default defineNuxtConfig({
  modules: ["@shooteger/nuxt-stripe"],
  stripe: {
    server: {
      // key is read from NUXT_STRIPE_SECRET_KEY automatically
      options: {
        // https://github.com/stripe/stripe-node#configuration
      },
    },
    client: {
      // key is read from NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY automatically
      options: {
        // https://stripe.com/docs/js/initializing#init_stripe_js-options
      },
      // manualClientLoad: true, // disable auto-load on mount
    },
  },
});

Via Runtime Config

export default defineNuxtConfig({
  modules: ["@shooteger/nuxt-stripe"],
  runtimeConfig: {
    stripe: {
      key: "", // NUXT_STRIPE_SECRET_KEY
      options: {},
    },
    public: {
      stripe: {
        key: "", // NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
        options: {},
      },
    },
  },
});

Usage

Server side

Use useServerStripe(event) inside any server route or API handler. The Stripe instance is cached per request context, so it is only initialized once per request.

// server/api/payment-intent.get.ts
import { defineEventHandler } from "h3";
import { useServerStripe } from "#stripe/server";

export default defineEventHandler(async (event) => {
  const stripe = useServerStripe(event);

  try {
    const paymentIntent = await stripe.paymentIntents.create({
      currency: "eur",
      amount: 2500, // €25.00
      automatic_payment_methods: { enabled: true },
    });

    return {
      clientSecret: paymentIntent.client_secret,
      error: null,
    };
  } catch (e) {
    return {
      clientSecret: null,
      error: e,
    };
  }
});

Client side

useClientStripe() wraps loadStripe and exposes a reactive stripe ref. By default, Stripe loads automatically when the component mounts.

<script setup lang="ts">
const { stripe, isLoading } = useClientStripe();
</script>

<template>
  <div v-if="isLoading">Loading Stripe...</div>
  <div v-else-if="stripe">Stripe ready</div>
</template>

The composable returns:

| Property | Type | Description | | ------------ | --------------------- | ----------------------------------- | | stripe | Ref<Stripe \| null> | The Stripe.js instance | | isLoading | Ref<boolean> | Whether Stripe is currently loading | | loadStripe | Function | Manually trigger Stripe load |

Manual load

If you want to control when Stripe loads (e.g. only on the checkout page), set manualClientLoad: true in your config and call loadStripe() yourself:

// nuxt.config.ts
stripe: {
  client: {
    manualClientLoad: true,
    key: process.env.NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
  },
}

const { loadStripe, stripe } = useClientStripe();

// Load only when needed
await loadStripe();

Full payment flow example

<script setup lang="ts">
const { stripe } = useClientStripe();

watch(stripe, async () => {
  if (!stripe.value) return;

  const { clientSecret } = await $fetch("/api/payment-intent");

  const elements = stripe.value.elements({ clientSecret });
  const paymentElement = elements.create("payment");
  paymentElement.mount("#payment-element");
});
</script>

Development

# Install dependencies
npm install

# Prepare dev environment (run this first)
npm run dev:prepare

# Start playground
npm run dev

# Build module
npm run prepack

# Run tests
npm run test

# Lint
npm run lint

# Release
npm run release

License

MIT — Originally forked from @unlok-co/nuxt-stripe by flozero, now partly rewritten and independently maintained.