@islaintel/islaintel-components

A modern TypeScript component library built with React, featuring JSX/TSX support and dual ESM/CJS module formats.

🚀 Features

• TypeScript First: Full TypeScript support with type definitions
• Modern Build System: Built with tsup for optimal bundle sizes
• Dual Module Support: ESM and CommonJS compatibility
• JSX/TSX Ready: Create React components with full TypeScript support
• Auto-build: Automatic builds before publishing
• Organized Structure: Logical grouping of components by category

📦 Install

npm install @islaintel/islaintel-components

🛠️ Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

1. Clone the repository

   git clone https://github.com/IslaIntel/islaintel-components.git
   cd islaintel-components

2. Install dependencies

   npm install

3. Build the project

   npm run build

🎨 Creating Assets

Component Structure with Sub-directories

Create your components organized by category in the src/ directory:

src/
├── components/
│   ├── hero/                    # Hero section components
│   │   ├── HeroSection/
│   │   │   ├── HeroSection.tsx
│   │   │   ├── HeroSection.test.tsx
│   │   │   └── index.ts
│   │   ├── HeroCard/
│   │   │   ├── HeroCard.tsx
│   │   │   └── index.ts
│   │   └── index.ts            # Hero category exports
│   ├── cta/                     # Call-to-action components
│   │   ├── CTAButton/
│   │   │   ├── CTAButton.tsx
│   │   │   └── index.ts
│   │   ├── CTACard/
│   │   │   ├── CTACard.tsx
│   │   │   └── index.ts
│   │   └── index.ts            # CTA category exports
│   ├── footer/                  # Footer components
│   │   ├── Footer/
│   │   │   ├── Footer.tsx
│   │   │   └── index.ts
│   │   ├── FooterLink/
│   │   │   ├── FooterLink.tsx
│   │   │   └── index.ts
│   │   └── index.ts            # Footer category exports
│   ├── ui/                      # Basic UI components
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   └── index.ts
│   │   ├── Card/
│   │   │   ├── Card.tsx
│   │   │   └── index.ts
│   │   └── index.ts            # UI category exports
│   └── index.ts                # Main library exports
├── hooks/
│   └── useToggle.ts
├── utils/
│   └── helpers.ts
└── index.ts

Example Category Structure

Hero Components

// src/components/hero/HeroSection/HeroSection.tsx
import React from 'react';

export interface HeroSectionProps {
  title: string;
  subtitle?: string;
  children?: React.ReactNode;
}

export function HeroSection({ title, subtitle, children }: HeroSectionProps) {
  return (
    <section className="hero-section">
      <h1>{title}</h1>
      {subtitle && <p>{subtitle}</p>}
      {children}
    </section>
  );
}

// src/components/hero/HeroSection/index.ts
export { HeroSection } from './HeroSection';
export type { HeroSectionProps } from './HeroSection';

// src/components/hero/index.ts
export { HeroSection } from './HeroSection';
export { HeroCard } from './HeroCard';
export type { HeroSectionProps } from './HeroSection';
export type { HeroCardProps } from './HeroCard';

CTA Components

// src/components/cta/CTAButton/CTAButton.tsx
import React from 'react';

export interface CTAButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary';
  onClick?: () => void;
}

export function CTAButton({ children, variant = 'primary', onClick }: CTAButtonProps) {
  return (
    <button 
      className={`cta-button cta-button--${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// src/components/cta/index.ts
export { CTAButton } from './CTAButton';
export { CTACard } from './CTACard';
export type { CTAButtonProps } from './CTAButton';
export type { CTACardProps } from './CTACard';

Main Library Exports

// src/components/index.ts
// Export all categories
export * from './hero';
export * from './cta';
export * from './footer';
export * from './ui';

// Or export specific categories
export { HeroSection, HeroCard } from './hero';
export { CTAButton, CTACard } from './cta';
export { Footer, FooterLink } from './footer';
export { Button, Card } from './ui';

// src/index.ts
export * from './components';
export * from './hooks';
export * from './utils';

Usage Patterns

Import Entire Categories

import { HeroSection, HeroCard } from '@islaintel/islaintel-components';

Import Specific Components

import { CTAButton } from '@islaintel/islaintel-components';

Import with TypeScript

import { HeroSection, type HeroSectionProps } from '@islaintel/islaintel-components';

🏗️ Building

Development Build

npm run build

This will:

• Compile TypeScript to JavaScript
• Generate type definitions (.d.ts)
• Create both ESM (.mjs) and CommonJS (.js) outputs
• Clean the dist/ folder before building

Build Output

dist/
├── index.d.ts      # TypeScript declarations
├── index.d.mts     # TypeScript declarations (ESM)
├── index.js        # CommonJS bundle
└── index.mjs       # ESM bundle

📤 Publishing

Pre-publish Checklist

1. Build the project

   npm run build

2. Test the build

   npm test

3. Check package contents

   npm pack --dry-run

Publishing Process

1. Commit your changes

   git add .
   git commit -m "feat: add hero and CTA components"

2. Bump version

   npm version patch    # 1.0.1 → 1.0.2
   npm version minor    # 1.0.1 → 1.1.0
   npm version major    # 1.0.1 → 2.0.0

3. Publish to npm

   npm publish

   Note: The prepublishOnly script will automatically run the build

4. Push tags to git

   git push --follow-tags

📖 Usage

ESM (Modern)

import { HeroSection, CTAButton } from '@islaintel/islaintel-components';

function App() {
  return (
    <div>
      <HeroSection title="Welcome" subtitle="Get started today">
        <CTAButton variant="primary" onClick={() => alert('Hello!')}>
          Get Started
        </CTAButton>
      </HeroSection>
    </div>
  );
}

CommonJS (Legacy)

const { HeroSection, CTAButton } = require('@islaintel/islaintel-components');

function App() {
  return (
    <div>
      <HeroSection title="Welcome" subtitle="Get started today">
        <CTAButton variant="primary" onClick={() => alert('Hello!')}>
          Get Started
        </CTAButton>
      </HeroSection>
    </div>
  );
}

TypeScript

import { 
  HeroSection, 
  CTAButton, 
  type HeroSectionProps, 
  type CTAButtonProps 
} from '@islaintel/islaintel-components';

const heroProps: HeroSectionProps = {
  title: 'Welcome',
  subtitle: 'Get started today'
};

const ctaProps: CTAButtonProps = {
  variant: 'primary',
  children: 'Get Started'
};

<HeroSection {...heroProps}>
  <CTAButton {...ctaProps} />
</HeroSection>

🧪 Testing

npm test

The test script runs a quick verification that the built package works correctly.

📁 Project Structure

islaintel-components/
├── src/                        # Source code
│   ├── components/             # React components
│   │   ├── hero/              # Hero section components
│   │   ├── cta/               # Call-to-action components
│   │   ├── footer/            # Footer components
│   │   ├── ui/                # Basic UI components
│   │   └── index.ts           # Component exports
│   ├── hooks/                 # Custom React hooks
│   ├── utils/                 # Utility functions
│   └── index.ts               # Main export file
├── dist/                       # Built output (auto-generated)
├── scripts/                    # Build scripts
├── package.json                # Package configuration
├── tsconfig.json               # TypeScript configuration
└── README.md                   # This file

🔧 Configuration

TypeScript

The project uses a modern TypeScript configuration optimized for:

• React JSX/TSX support
• Modern ES2020 features
• Strict type checking
• Declaration file generation

Build System

Built with tsup for:

• Fast incremental builds
• Dual ESM/CJS output
• Automatic type generation
• Tree shaking optimization

🤝 Contributing

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

📄 License

This project is licensed under the ISC License.