@playful_process/components

v1.0.9

Published

a month ago

Shared auth components for Recursive.eco projects (DualAuth, AuthProvider, PageModals)

Downloads

0High
0Medium
0Low

playful_process

react nextjs supabase auth ui-components recursive-eco

Recursive Components

NPM Package: @playful_process/components

Shared UI components for the Recursive.eco ecosystem, published to npm for easy installation across all projects.

Quick Start

npm install @playful_process/components

// Auth components (from npm package)
import { OTPAuth, AuthProvider, useAuth, PageModals } from '@playful_process/components';

// Layout components (create locally in your project - see recursive-starter for reference)
import { Header } from '@/components/layout/Header';
import { Footer } from '@/components/layout/Footer';

Projects Using This Package

recursive-channels-fresh (channels.recursive.eco)
jongu-tool-best-possible-self (journal.recursive.eco)
recursive-creator (creator.recursive.eco)
recursive-starter - Minimal Next.js 15 starter template

New to Recursive.eco?

Use recursive-starter as your starting point:

Production-tested auth (email + OTP)
All components pre-configured
Supabase integration ready
Just copy, customize, and deploy!

🎯 Hybrid Approach: Auth in NPM, Layout Local

Why this approach?

✅ Auth components in npm package (OTPAuth, AuthProvider, PageModals)

Security-critical code shared across all projects
Updates propagate automatically via npm update
One tested implementation, no divergence

✅ Layout components local to each project (Header, Footer)

Each project has different navigation needs
Easy to customize without fighting shared code
No version conflicts when you want project-specific changes

Best of both worlds: Shared auth security + layout flexibility!

📁 What's Included in NPM Package

Auth components only - layout components (Header/Footer) are kept local to each project for customization.

@playful_process/components/
├── components/
│   ├── OTPAuth.tsx            # OTP-based authentication component
│   ├── AuthProvider.tsx        # Auth context provider
│   └── PageModals.tsx          # Modal management component
└── lib/
    ├── supabase-client.ts      # Client-side Supabase config
    └── supabase-server.ts      # Server-side Supabase config

Note: Header and Footer components are in inactive/layout/ for reference. Copy them to your project from recursive-starter and customize as needed.

🔄 How to Use These Components

1. Install the Package

npm install @playful_process/components

2. Import Auth Components

// From npm package
import {
  OTPAuth,
  AuthProvider,
  useAuth,
  PageModals
} from '@playful_process/components';

// From your local components (copy from recursive-starter)
import { Header } from '@/components/layout/Header';
import { Footer } from '@/components/layout/Footer';

3. Set Up Supabase

Create .env.local with your Supabase credentials:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

4. Add AuthProvider to Layout

// app/layout.tsx
import { AuthProvider } from '@playful_process/components';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}

5. Use Components in Your App

// app/page.tsx
import { useAuth, PageModals } from '@playful_process/components';

export default function Home() {
  const { user, status, signOut } = useAuth();

  return (
    <>
      <main>
        {status === 'authenticated' ? (
          <p>Welcome, {user?.email}!</p>
        ) : (
          <p>Please sign in</p>
        )}
      </main>
      <PageModals />
    </>
  );
}

Updating to Latest Version

npm install @playful_process/components@latest

🛠️ Component Details

OTPAuth.tsx

Purpose: OTP-based email authentication
Features:
- Standard flow: Email entry → OTP code verification
- Direct entry: "Already have a code?" - Enter email + OTP together
- Auto-closes on successful auth
- Escape key to close
- Clean, dark-mode-ready UI
Use case: Direct entry helps when user already has the OTP code from their email
Uses: AuthProvider (via useAuth hook)

AuthProvider.tsx

Purpose: React Context for global auth state
Provides:
- user: Current Supabase user object
- status: 'loading' | 'authenticated' | 'unauthenticated'
- signOut: Function to sign out

Supabase Utilities

supabase-client.ts: Client-side Supabase client (environment-aware cookies)
supabase-server.ts: Server-side Supabase client (Next.js server components)

📝 Development Workflow

For Component Maintainers:

Update component in recursive-components
Build package: npm run build
Bump version in package.json (follow semver)
Publish to npm: npm publish
Update projects: Run npm install @playful_process/components@latest in each project

🎨 Styling Notes

All components use Tailwind CSS utility classes with dark mode support:

Light mode: bg-white, text-gray-900
Dark mode: dark:bg-gray-900, dark:text-gray-100

🔐 Environment Variables

All projects using these components need these Supabase env vars:

NEXT_PUBLIC_SUPABASE_URL=https://evixjvagwjmjdjpbazuj.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key  # Server-side only

📌 Version History

v1.0.8 (2025-11-07): Adopted hybrid approach - auth in npm, layouts local
v1.0.5 (2025-11-07): Fixed path alias issue (@/lib → ../lib) for proper npm imports
v1.0.4 (2025-11-05): Added direct OTP entry mode
v1.0.3: PageModals component added
v1.0.1: Initial npm publication
2025-01-05: Project started with Header, Footer, OTPAuth, AuthProvider

🛠️ Contributing

This is the source code for the npm package. To contribute:

Clone this repo
Make changes to components
Test locally with npm run build
Submit PR or publish new version if you're a maintainer

📚 Learn More

Starter Template: See recursive-starter for complete setup example
Supabase Docs: supabase.com/docs
Next.js Docs: nextjs.org/docs

📄 License

CC BY-SA 4.0

Built with curiosity. Shared with courage. Maintained with kindness. Exploring beauty.

— PlayfulProcess