📦 Using @lantern/stripe-utility in Other Projects

This guide explains how to consume the @lantern/stripe-utility package from other projects. It covers common workflows for local development, monorepos, and publishing to a registry.

🎯 Three Ways to Use This Package

• Option A — NPM workspaces (recommended for monorepos)
• Option B — npm link (local testing)
• Option C — Publish to an npm registry (private or public)

📁 Option A — NPM Workspaces (Monorepo)

Best when your repository contains multiple packages and you want them linked automatically.

1. In your repo root package.json, add a workspaces entry that matches your packages layout (example):

{
  "private": true,
  "workspaces": ["packages/*"]
}

2. Build the utility package (from the package folder):

cd packages/stripe-utility
npm run build

3. From the repo root, run:

npm install

This will link local workspace packages into consuming packages. In a consuming package's package.json, add:

{
  "dependencies": {
    "@lantern/stripe-utility": "*"
  }
}

4. Restart the consuming project's dev server so it picks up the newly built output.

Notes:

• Keep stripe-utility built to dist/ when consuming locally.
• If you change source in stripe-utility/src/, rebuild (npm run build) and restart the consumer.

🔗 Option B — npm link (Local testing)

Use npm link when the consuming project is outside your monorepo or you want quick local testing.

1. Build the package:

cd packages/stripe-utility
npm run build

2. Create a global link from the package folder:

npm link

3. In the other project, link the package:

cd /path/to/other/project
npm link @lantern/stripe-utility

4)When finished testing, unlink:

# in the other project
npm unlink @lantern/stripe-utility

# in the package folder (undo global link)
cd packages/stripe-utility
npm unlink

Notes: -npm link is convenient but can lead to dependency resolution differences vs installed packages. Use it for quick testing only.

📤 Option C — Publish to an NPM Registry

For sharing across repositories or teams, publish the package to a registry (public or private).

1. Ensure private: false (or remove private) in packages/stripe-utility/package.json and set name and version appropriately.

2. Build and publish:

cd packages/stripe-utility
npm run build
npm publish

3. Install in consumer projects:

npm install @lantern/stripe-utility

📦 Package configuration checklist

Recommended fields for package.json of the package:

{
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

Notes:

• type: "module" helps consumers use the package as ESM.
• The package relies on Stripe client libraries as peer dependencies. Consumers should install @stripe/react-stripe-js and @stripe/stripe-js themselves.

🛠 Development workflow

1. Edit source in packages/stripe-utility/src/.
2. Build the package:

cd packages/stripe-utility
npm run build

3. Restart the consumer dev server so it picks up the changed build.

Quick helper (optional): from the repo root you can run a script to build all packages or watch the build if you add such scripts.

🔍 Example: Using the package in a server

import express from 'express';
import { createStripeService } from '@lantern/stripe-utility';

const app = express();
const stripe = createStripeService({ secretKey: process.env.STRIPE_SECRET_KEY! });

app.post('/create-payment', express.json(), async (req, res) => {
  const result = await stripe.createPaymentIntent({ amountCents: req.body.amount });
  res.json(result);
});

💡 Example: Using the package in a React app

import React from 'react';
import { Elements } from '@stripe/react-stripe-js';
import { initStripe } from '@lantern/stripe-utility';

const stripePromise = initStripe(process.env.VITE_STRIPE_PUBLISHABLE_KEY!);

function App({ clientSecret }: { clientSecret: string }) {
  return (
    <Elements stripe={stripePromise} options={{ clientSecret }}>
      {/* your payment form here */}
    </Elements>
  );
}

❗ Common issues and fixes

• Cannot find module @lantern/stripe-utility:

  • Ensure dist/ exists (npm run build in the package) and install from the repo root when using workspaces (npm install).
  • If consuming via file: spec in package.json, ensure the path is correct relative to the consuming package.

• confirmPayment or other exports not found in the frontend:

  • Rebuild the package and ensure the build outputs ESM (type: "module" in package.json and module/moduleResolution appropriate in tsconfig.json).

• Types not found:

  • Ensure dist/index.d.ts is produced and types is set in package.json.

✅ Recommended practice

• Keep UI components and Stripe React bindings installed by the consumer (@stripe/react-stripe-js, @stripe/stripe-js) — stripe-utility provides helpers and server utilities, not UI components.
• Use workspaces for local development when possible, or npm link for quick tests.
• Publish to your registry for team-wide sharing.