A Nuxt 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: {
      // secretKey is read from NUXT_STRIPE_SECRET_KEY automatically
      options: {
        // https://github.com/stripe/stripe-node#configuration
      },
    },
    client: {
      // publishableKey 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: {
      secretKey: "", // NUXT_STRIPE_SECRET_KEY
      options: {},
    },
    public: {
      stripe: {
        publishableKey: "", // 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,
    publishableKey: 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>

Migration

v1.x → v2.x

The only breaking change is the naming of the keys. In v1 both the server and the client key were just called key, which was confusing. Since v2 they are called what they actually are: secretKey on the server and publishableKey on the client.

In v1 you also had to wire the env variables yourself via process.env in the config. Since v2, Nuxt picks the keys up automatically from NUXT_STRIPE_SECRET_KEY and NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — no process.env in the config needed anymore.

	v1	v2
Server key (module option / runtime config)	server.key	server.secretKey
Client key (module option / runtime config)	client.key	client.publishableKey
Server env variable	STRIPE_SECRET_KEY (manually via process.env)	NUXT_STRIPE_SECRET_KEY (picked up automatically)
Client env variable	STRIPE_PUBLISHABLE_KEY (manually via process.env)	NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY (picked up automatically)

To upgrade:

1. Update the package: npm install @shooteger/nuxt-stripe@latest
2. In your .env (and on your hosting provider), rename STRIPE_SECRET_KEY to NUXT_STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY to NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY.
3. In your nuxt.config.ts, remove the key: process.env... lines — the keys are now read from the env variables automatically. If you still want to set them in the config, use the new names secretKey / publishableKey.

That's it. The composables useServerStripe(event) and useClientStripe() work exactly the same as in v1, no code changes needed there.

Development

# Install dependencies
pnpm install

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

# Start playground
pnpm dev

# Build module
pnpm prepack

# Run tests
pnpm test

# Lint
pnpm lint

# Release
pnpm release

License

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