Skip to content

LIBRARY_INTEGRATION.md

Latest commit

 

History

History
227 lines (179 loc) · 5.94 KB

LIBRARY_INTEGRATION.md

File metadata and controls

227 lines (179 loc) · 5.94 KB

Selfx402PayWidget Library Integration

Successfully created and integrated the @selfx402/pay-widget NPM library into the Selfx402Pay project.

What Was Done

1. Library Creation (/Selfx402PayWidget)

Created a complete, production-ready NPM package:

Structure:

Selfx402PayWidget/
├── dist/                         # Built output
│   ├── index.js (48KB)          # CommonJS bundle
│   ├── index.mjs (41KB)         # ES Module bundle
│   ├── index.d.ts (3.5KB)       # TypeScript declarations
│   └── index.d.mts (3.5KB)      # ESM TypeScript declarations
├── src/
│   ├── components/
│   │   ├── ui/                  # Base UI components
│   │   ├── payment-form.tsx
│   │   ├── payment-form-minimal.tsx
│   │   └── payment-success.tsx
│   ├── lib/utils.ts
│   └── index.ts
├── package.json
├── tsconfig.json
├── README.md
└── .npmignore

Exported Components:

  • PaymentForm - Full-featured payment form
  • PaymentFormMinimal - Compact form with USDC balance
  • PaymentSuccess - Success screen with animations
  • Button, Card, Input, Label - UI primitives
  • cn() - Utility function

Build Output:

  • ✅ ESM + CJS dual package
  • ✅ Full TypeScript type definitions
  • ✅ Optimized bundles with tree-shaking support
  • ✅ 20KB gzipped package size

2. Local Installation

Installed the library locally in Selfx402Pay:

# In Selfx402PayWidget/
npm run build
npm pack
# Created: selfx402-pay-widget-0.1.0.tgz

# In Selfx402Pay/
npm install ../Selfx402PayWidget/selfx402-pay-widget-0.1.0.tgz

3. Code Refactoring

Before:

import PaymentForm from "@/components/payment-form"
import PaymentFormMinimal from "@/components/payment-form-minimal"

After:

import { PaymentForm, PaymentFormMinimal } from "@selfx402/pay-widget"

Moved to Backup:

  • /components/.old-payment-components/payment-form.tsx (archived)
  • /components/.old-payment-components/payment-form-minimal.tsx (archived)
  • /components/.old-payment-components/payment-success.tsx (archived)

4. Verification

✅ Dev Server: Successfully starts on port 3001 ✅ Hot Reload: Works correctly with library imports ✅ Type Safety: Full TypeScript support with autocomplete ✅ No Self-References: Clean separation between app and library

Benefits

1. Clean Architecture

  • ✅ No circular dependencies
  • ✅ Clear separation of concerns
  • ✅ Reusable components across projects

2. Developer Experience

  • ✅ Single source of truth for payment components
  • ✅ Version control for component library
  • ✅ Easy updates across all consuming projects

3. Maintainability

  • ✅ Bug fixes in one place
  • ✅ Consistent behavior across implementations
  • ✅ Independent testing of library

4. Distribution

  • ✅ Ready for NPM publication
  • ✅ Can be used in any React/Next.js project
  • ✅ Includes comprehensive documentation

Usage in Selfx402Pay

The app now cleanly imports payment components from the library:

import { PaymentForm, PaymentFormMinimal } from "@selfx402/pay-widget"

export default function Home() {
  return (
    <Tabs>
      <TabsContent value="regular">
        <PaymentForm
          vendorUrl="http://localhost:3000"
          apiEndpoint="/api/demo"
          showDeepLink={false}
          onPaymentSuccess={(data) => console.log(data)}
          onPaymentFailure={(error) => console.error(error)}
        />
      </TabsContent>

      <TabsContent value="minimal">
        <PaymentFormMinimal
          vendorUrl="http://localhost:3000"
          showDeepLink="both"
        />
      </TabsContent>
    </Tabs>
  )
}

Next Steps

For Development

  1. Continue using the library locally for now
  2. Make updates in /Selfx402PayWidget/src/
  3. Rebuild and reinstall when changes are made: 
    cd Selfx402PayWidget
npm run build
npm pack
cd ../Selfx402Pay
npm install ../Selfx402PayWidget/selfx402-pay-widget-0.1.0.tgz

For Production (When Ready)

  1. Publish to NPM:

    cd Selfx402PayWidget
npm login
npm publish --access public

  2. Update Selfx402Pay:

    cd Selfx402Pay
npm uninstall @selfx402/pay-widget
npm install @selfx402/pay-widget

  3. Remove Tarball Installation:

    • Update package.json to use "@selfx402/pay-widget": "^0.1.0" instead of file path

For Other Projects

Install the library in any React/Next.js project:

npm install @selfx402/pay-widget

# Peer dependencies (if not already installed)
npm install react react-dom wagmi viem @tanstack/react-query

Files Changed

Selfx402Pay

  • ✅ app/page.tsx - Updated imports to use library
  • ✅ components/payment-form.tsx - Moved to .old-payment-components/
  • ✅ components/payment-form-minimal.tsx - Moved to .old-payment-components/
  • ✅ components/payment-success.tsx - Moved to .old-payment-components/
  • ✅ package.json - Added @selfx402/pay-widget dependency

Selfx402PayWidget (New)

  • ✅ Complete library structure created
  • ✅ All components extracted and adapted
  • ✅ Build system configured (tsup)
  • ✅ TypeScript declarations generated
  • ✅ README documentation complete
  • ✅ NPM package ready for publication

Troubleshooting

If Updates Don't Reflect

  1. Rebuild the library:

    cd Selfx402PayWidget
npm run build

  2. Clear Next.js cache:

    cd Selfx402Pay
rm -rf .next
npm run dev

If Types Are Missing

Reinstall the library:

cd Selfx402Pay
npm uninstall @selfx402/pay-widget
npm install ../Selfx402PayWidget/selfx402-pay-widget-0.1.0.tgz

Summary

✨ Success! The Selfx402Pay project now uses a clean, professional library architecture with no self-references. The payment components are fully encapsulated in the @selfx402/pay-widget package, ready for reuse across multiple projects and publication to NPM.