npm package: @lantern-ai/stripe-utility
Description: 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.
Latest version: 0.2.1

# 📦 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):

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

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

```bash
cd packages/stripe-utility
npm run build
```

3) From the repo root, run:

```bash
npm install
```

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

```json
{
  "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:

```bash
cd packages/stripe-utility
npm run build
```

2) Create a global link from the package folder:

```bash
npm link
```

3) In the other project, link the package:

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

4)When finished testing, unlink:

```bash
# 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:

```bash
cd packages/stripe-utility
npm run build
npm publish
```

3) Install in consumer projects:

```bash
npm install @lantern/stripe-utility
```

---

## 📦 Package configuration checklist

Recommended fields for `package.json` of the package:

```json
{
  "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:

```bash
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

```ts
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

```tsx
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.