Skip to content

Latest commit

Β 

History

History
437 lines (348 loc) Β· 9.62 KB

File metadata and controls

437 lines (348 loc) Β· 9.62 KB

Fever Component Library - Integration Guide

πŸš€ Quick Integration

1. Import Components

// Named imports for specific components
import { Button, Input, Modal, Card } from '../fever-components/src';

// Import all components
import * as FeverComponents from '../fever-components/src';

// Import with custom naming
import { Button as FeverButton } from '../fever-components/src';

2. Include Base Styles

The components require the base CSS file to be loaded:

// In your main App.tsx or layout component
import '../fever-components/src/styles/base.css';

// Or in your global CSS file
@import '../fever-components/src/styles/base.css';

3. Basic Usage

import React, { useState } from 'react';
import { Button, Alert, Modal } from '../fever-components/src';

function MyApp() {
  const [showAlert, setShowAlert] = useState(false);
  const [showModal, setShowModal] = useState(false);

  return (
    <div className="p-6">
      <Button
        variant="primary"
        onClick={() => setShowAlert(true)}
      >
        Show Alert
      </Button>

      {showAlert && (
        <Alert
          variant="success"
          title="Success!"
          description="Component integration is working!"
          onClose={() => setShowAlert(false)}
        />
      )}

      <Modal
        open={showModal}
        onClose={() => setShowModal(false)}
        title="Welcome to Fever Components"
        description="You're all set up!"
      />
    </div>
  );
}

πŸ“ Project Structure Integration

Recommended File Organization

your-project/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ ui/                    # Your existing components
β”‚   β”‚   └── fever/                 # Fever component customizations
β”‚   β”œβ”€β”€ pages/
β”‚   └── App.tsx
β”œβ”€β”€ fever-components/              # Fever component library
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ styles/
β”‚   β”‚   └── tokens/
β”‚   └── docs/
└── package.json

CSS Loading Strategy

Option 1: Global Import (Recommended)

// In your main entry point (App.tsx or index.tsx)
import '../fever-components/src/styles/base.css';
import './your-app-styles.css'; // Your custom styles after

Option 2: Component-Level Import

// In individual components that use Fever components
import '../fever-components/src/styles/base.css';
import { Button, Alert } from '../fever-components/src';

Option 3: Build Tool Integration

// In your webpack.config.js or vite.config.js
{
  resolve: {
    alias: {
      '@fever': path.resolve(__dirname, 'fever-components/src')
    }
  }
}

// Then import as:
import { Button } from '@fever';
import '@fever/styles/base.css';

πŸ”§ Advanced Integration

Custom Component Wrappers

Create your own wrapper components for custom behavior:

// components/fever/FeverButton.tsx
import React from 'react';
import { Button, ButtonProps } from '../../fever-components/src';

interface CustomButtonProps extends ButtonProps {
  loading?: boolean;
  trackingId?: string;
}

export function FeverButton({
  loading,
  trackingId,
  onClick,
  children,
  ...props
}: CustomButtonProps) {
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    // Add your tracking logic
    if (trackingId) {
      analytics.track('button_click', { trackingId });
    }

    if (onClick && !loading) {
      onClick(e);
    }
  };

  return (
    <Button
      {...props}
      onClick={handleClick}
      disabled={loading || props.disabled}
    >
      {loading ? 'Loading...' : children}
    </Button>
  );
}

Theme Customization

Override CSS custom properties to customize the design:

/* your-custom-theme.css */
:root {
  /* Override primary color */
  --fever-primary: #your-brand-color;
  --fever-primary-dark: #your-brand-color-dark;

  /* Override fonts */
  --fever-font-family: 'Your Custom Font', sans-serif;

  /* Override spacing */
  --fever-spacing-scale: 1.2; /* Increase all spacing by 20% */
}

/* Component-specific overrides */
.fever-button-primary {
  border-radius: 2rem; /* Custom button radius */
}

.fever-modal {
  backdrop-filter: blur(8px); /* Add backdrop blur */
}

Type Augmentation

Extend component types for your project:

// types/fever-extensions.d.ts
import { ButtonProps as OriginalButtonProps } from '../fever-components/src';

declare module '../fever-components/src' {
  interface ButtonProps extends OriginalButtonProps {
    trackingId?: string;
    analyticsCategory?: string;
  }
}

🎯 Migration Strategies

From Existing UI Library

Gradual Migration

// Step 1: Import both libraries
import { Button as OldButton } from 'your-old-library';
import { Button as FeverButton } from '../fever-components/src';

// Step 2: Use component aliases during migration
const Button = process.env.NODE_ENV === 'development'
  ? FeverButton
  : OldButton;

// Step 3: Gradually replace components
function MyComponent() {
  return (
    <div>
      <OldButton>Legacy Button</OldButton>
      <FeverButton variant="primary">New Fever Button</FeverButton>
    </div>
  );
}

Component Mapping

// Create a mapping file for easy migration
// migration/component-map.ts
export const ComponentMap = {
  // Map old components to new ones
  'Button': () => import('../fever-components/src').then(m => m.Button),
  'Input': () => import('../fever-components/src').then(m => m.Input),
  'Modal': () => import('../fever-components/src').then(m => m.Modal),
};

// Use in your components
const Button = ComponentMap.Button;

πŸ”¨ Development Workflow

Hot Reloading Setup

For development, you may want to link the component library:

# In fever-components directory
npm link

# In your project directory
npm link fever-components

Testing Integration

// __tests__/FeverIntegration.test.tsx
import { render, screen } from '@testing-library/react';
import { Button, Alert } from '../fever-components/src';

// Mock CSS imports for testing
jest.mock('../fever-components/src/styles/base.css', () => ({}));

describe('Fever Components Integration', () => {
  test('Button renders correctly', () => {
    render(<Button>Test Button</Button>);
    expect(screen.getByRole('button')).toBeInTheDocument();
  });

  test('Alert displays message', () => {
    render(
      <Alert title="Test Alert" description="Test message" />
    );
    expect(screen.getByText('Test Alert')).toBeInTheDocument();
  });
});

Bundle Size Optimization

// webpack.config.js - Tree shaking setup
module.exports = {
  optimization: {
    usedExports: true,
    sideEffects: [
      '*.css',
      '../fever-components/src/styles/base.css'
    ]
  }
};

// Only import what you need
import { Button, Input } from '../fever-components/src';
// Instead of: import * from '../fever-components/src';

🎨 Design System Integration

Using Design Tokens

// Access design tokens in your components
import { tokens } from '../fever-components/src';

function CustomComponent() {
  return (
    <div style={{
      color: tokens.colors.primary,
      fontSize: tokens.typography.textSizes.lg,
      padding: tokens.spacing.spacing4
    }}>
      Custom styled with Fever tokens
    </div>
  );
}

CSS Custom Properties

/* Use Fever tokens in your CSS */
.custom-element {
  background: var(--fever-primary);
  color: var(--fever-background);
  padding: var(--fever-spacing-4);
  border-radius: var(--fever-radius-md);
  transition: all 0.2s ease;
}

.custom-element:hover {
  background: var(--fever-primary-dark);
  transform: translateY(-1px);
}

🚨 Common Issues & Solutions

Issue: Components not styled correctly

// ❌ Missing CSS import
import { Button } from '../fever-components/src';

// βœ… Include CSS import
import '../fever-components/src/styles/base.css';
import { Button } from '../fever-components/src';

Issue: TypeScript errors

// ❌ Missing type imports
const button: ButtonProps = { variant: 'primary' };

// βœ… Import types
import type { ButtonProps } from '../fever-components/src';
const button: ButtonProps = { variant: 'primary' };

Issue: CSS conflicts

/* ❌ Global styles overriding Fever components */
button {
  background: blue !important;
}

/* βœ… Scope your styles */
.my-app button:not([class*="fever-"]) {
  background: blue;
}

πŸ“¦ Production Deployment

Build Optimization

// vite.config.js
export default {
  build: {
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM'
        }
      }
    }
  }
};

CDN Integration (Future)

<!-- Future CDN setup -->
<link rel="stylesheet" href="https://cdn.fever.com/components/latest/styles.css">
<script src="https://cdn.fever.com/components/latest/index.js"></script>

🀝 Contributing Back

Component Requests

  • Create issues for missing components
  • Follow the existing component patterns
  • Include use cases and design requirements

Bug Reports

  • Include component version and browser info
  • Provide minimal reproduction examples
  • Check the testing page first

Feature Enhancements

  • Propose via GitHub issues
  • Consider backward compatibility
  • Include documentation updates

πŸ”₯ Ready to build with Fever Components?

Start with the Quick Start section and check out our interactive testing page for live examples!

Need help? Check our API Reference or visit the main documentation.