SubOS Frontend - React Component Library

A comprehensive React component library for subscription management, billing, and payment processing. SubOS Frontend provides a collection of reusable UI components designed to be integrated into React applications for managing subscriptions, pricing, billing, and account logic.

🚀 Features

• Plan Management Components - Browse, select, and display subscription plans
• Payment Processing - Stripe-integrated payment components and flows
• Subscription Management - View, manage, and cancel subscriptions
• Transaction History - Display payment history and invoices
• Billing Components - Handle billing cycles, pricing tiers, and coupons
• TypeScript Support - Full TypeScript definitions included
• Modern UI - Clean, responsive components built with Tailwind CSS
• Tree Shaking - Optimized bundle size with ESM support

📦 Installation

npm install subos-frontend
# or
yarn add subos-frontend
# or
pnpm add subos-frontend

🎯 Quick Start

1. Import Styles

Import the CSS file in your app's entry point:

import 'subos-frontend/style.css';

2. Configure SubOS

You have two options to configure the library:

Option A: Runtime Configuration (Recommended)

import { configureSubOS } from 'subos-frontend';

configureSubOS({
  apiEndpoint: 'https://your-api.com/api/v1',
  projectId: 'your-project-id',
  stripePublishableKey: 'pk_live_xxx', // Optional, for payment features
  appName: 'Your App Name',
  appEnvironment: 'production'
});

Option B: Environment Variables

Create a .env file in your project root (copy from .env.example included in the package):

VITE_API_ENDPOINT=https://your-api.com/api/v1
VITE_PROJECT_ID=your-project-id
VITE_APP_NAME=Your App Name
VITE_APP_ENVIRONMENT=production

3. Use the Complete App Component

For a full subscription management experience, use the App component:

import { App } from 'subos-frontend';

function MyApp() {
  // Get the authenticated user's external ID from your auth system
  const userExternalId = getCurrentUser().externalId; // Your auth logic here
  
  return (
    <App externalId={userExternalId} />
  );
}

4. Use Individual Components

For more granular control, import specific components:

import { PlanCard, PlansGrid, SubscriptionDetails } from 'subos-frontend';

function MyApp() {
  return (
    <div>
      <PlansGrid 
        plans={plans}
        onPlanSelect={handlePlanSelect}
        billingCycle="monthly"
      />
    </div>
  );
}

🧩 Available Components

Plan Components

import { 
  PlanCard, 
  PlansGrid, 
  PlanSelector, 
  BillingCycleToggle,
  TierFilterDropdown 
} from 'subos-frontend';

// Display individual plan
<PlanCard 
  plan={plan}
  isSelected={false}
  billingCycle="monthly"
  onSelect={handleSelect}
/>

// Display grid of plans
<PlansGrid 
  plans={plans}
  selectedPlan={selectedPlan}
  billingCycle="monthly"
  onPlanSelect={handlePlanSelect}
/>

// Billing cycle toggle
<BillingCycleToggle 
  value="monthly"
  onChange={handleCycleChange}
/>

Payment Components

import { 
  PaymentSuccessView, 
  PaymentCancelView,
  ChangeCardButton 
} from 'subos-frontend';

// Payment result pages
<PaymentSuccessView />
<PaymentCancelView />

// Change payment method
<ChangeCardButton onCardChange={handleCardChange} />

Subscription Components

import { SubscriptionDetails } from 'subos-frontend';

<SubscriptionDetails 
  subscription={subscription}
  onCancel={handleCancel}
  onUpgrade={handleUpgrade}
/>

Transaction Components

import { TransactionList, TransactionModal } from 'subos-frontend';

<TransactionList 
  transactions={transactions}
  onViewInvoice={handleViewInvoice}
/>

<TransactionModal 
  transaction={transaction}
  isOpen={isModalOpen}
  onClose={handleClose}
/>

Utility Components

import { Layout, LogoInline, CheckIcon, Pagination } from 'subos-frontend';

// Layout wrapper
<Layout>
  <YourContent />
</Layout>

// Pagination
<Pagination 
  currentPage={1}
  totalPages={10}
  onPageChange={handlePageChange}
/>

⚙️ Environment Configuration

Configuration Options

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | VITE_API_ENDPOINT | Your SubOS backend API URL | ✅ | http://localhost:3002/api/v1 | | VITE_PROJECT_ID | Your project ID from SubOS backend | ✅ | - | | VITE_APP_NAME | Your application name | ❌ | SubOS Frontend | | VITE_APP_VERSION | Your application version | ❌ | 1.0.0 | | VITE_APP_ENVIRONMENT | Environment (development/production) | ❌ | development | | VITE_DEBUG | Enable debug mode | ❌ | false |

Runtime Configuration API

import { configureSubOS, getApiBaseUrl, getProjectId } from 'subos-frontend';

// Configure at app startup
configureSubOS({
  apiEndpoint: 'https://api.mycompany.com/api/v1',
  projectId: 'my-project-id',
  stripePublishableKey: 'pk_live_xxx',
  appName: 'My Company App',
  appEnvironment: 'production',
  debug: false
});

// Access configured values
const apiUrl = getApiBaseUrl();
const projectId = getProjectId();

Environment Template

Copy the included .env.example file to your project and customize:

cp node_modules/subos-frontend/.env.example .env

🔧 API Integration

The library includes a complete API client for backend integration:

import { 
  plansApi, 
  subscriptionApi, 
  customerApi, 
  transactionApi
} from 'subos-frontend';

// Fetch plans
const { data: plans } = await plansApi.getPlans();

// Get subscription
const { data: subscription } = await subscriptionApi.getActiveSubscription(userId);

// Create checkout session
const { data: session } = await plansApi.createPaymentSession(planCode, {
  customerEmail: '[email protected]',
  couponCode: 'DISCOUNT10'
});

🎨 Styling & Customization

Components are styled with Tailwind CSS and support extensive customization:

1. Use default styles - Import the included CSS file
2. Customize with Tailwind - Override classes using Tailwind utilities
3. Custom CSS - Override component styles with custom CSS
4. Font Customization - Control font sizes, weights, and colors for all text elements

Font Customization

SubOS Frontend provides comprehensive font customization options. You can control the typography of all text elements while maintaining sensible defaults:

:root {
  /* Customize font sizes */
  --subos-font-size-plan-title: 1.5rem;
  --subos-font-size-plan-card-title: 1.5rem;
  --subos-font-size-button-text: 1rem;
  
  /* Customize font weights */
  --subos-font-weight-plan-title: 700;
  --subos-font-weight-subscription-value: 600;
  
  /* Customize colors */
  --subos-color-plan-description: #6b7280;
  --subos-color-button-text: #3b82f6;
}

Or use the theme provider:

import { SubOSThemeProvider } from 'subos-frontend';

const theme = {
  fontSizes: {
    planTitle: '1.5rem',
    buttonText: '1rem',
  },
  fontWeights: {
    planTitle: 700,
    subscriptionValue: 600,
  },
  fontColors: {
    planDescription: '#6b7280',
    buttonText: '#3b82f6',
  },
};

<SubOSThemeProvider theme={theme}>
  {/* Your components */}
</SubOSThemeProvider>

📖 See FONT_CUSTOMIZATION.md for complete documentation and examples.

📋 TypeScript Support

Full TypeScript definitions are included:

import type { 
  Plan, 
  Subscription, 
  Transaction, 
  PlanCardProps,
  ApiResponse 
} from 'subos-frontend';

🔄 Development Setup

For contributing or local development:

Prerequisites

• Node.js (v20.19.0 or higher)
• pnpm (recommended)

Setup

git clone <repository-url>
cd subos-frontend
pnpm install
pnpm dev

Build Library

pnpm build

This generates:

• /dist/index.js - ESM bundle
• /dist/index.cjs - CommonJS bundle
• /dist/index.d.ts - TypeScript declarations
• /dist/style.css - Compiled styles

Project Structure

subos-frontend/
├── src/
│   ├── api/          # API utilities and endpoints
│   ├── assets/       # Static assets
│   ├── components/   # React components
│   ├── config/       # Configuration files
│   ├── hooks/        # Custom React hooks
│   ├── pages/        # Page components
│   ├── styles/       # Global styles
│   ├── types/        # TypeScript type definitions
│   ├── utils/        # Utility functions
│   ├── App.tsx       # Main App component with routing
│   └── main.tsx      # Application entry point
├── public/           # Public assets
└── .env              # Environment variables

Backend Integration

This frontend is designed to work with the SubOS backend API (NestJS, TypeScript, PostgreSQL, TypeORM).

Configuration

1. Configure the API endpoint in your environment variables (.env file):

   VITE_API_URL=http://localhost:3000

2. The API configuration is handled in src/config/ directory.

Backend Requirements

• NestJS backend with TypeScript
• PostgreSQL database with TypeORM
• CORS enabled for frontend domain
• API endpoints for subscription management

📚 Available Scripts

• pnpm build - Build the library (ESM + CommonJS + types)
• pnpm build:watch - Build in watch mode
• pnpm dev - Start development server
• pnpm lint - Run ESLint

🔗 Peer Dependencies

Ensure your project includes these peer dependencies:

{
  "peerDependencies": {
    "react": ">=18",
    "react-dom": ">=18", 
    "react-router-dom": ">=6",
    "@stripe/react-stripe-js": ">=2",
    "@stripe/stripe-js": ">=1"
  }
}

🏗️ Tech Stack

• Frontend: React 19, TypeScript
• Build Tool: tsup (ESM + CommonJS)
• Styling: Tailwind CSS
• Payment: Stripe integration
• Routing: React Router DOM
• Package Manager: pnpm

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team

Built with ❤️ by the Knovator team