Cohere Components

A library of reusable React components for the Cohere project, built with Next.js, TypeScript, and Tailwind CSS.

📖 Component Documentation

View Interactive Component Library →

Browse all 51 components with live previews, interactive controls, and code examples in our Storybook documentation.

📦 Installation

Step 1: Get a GitHub Personal Access Token

Each developer needs their own GitHub Personal Access Token (PAT) to install packages from GitHub Packages:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
   • Direct link: https://github.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a descriptive name (e.g., "npm-packages-read")
4. Select the read:packages scope (this allows downloading packages)
5. Set an expiration date (recommended: 90 days or 1 year)
6. Click "Generate token"
7. Copy the token immediately (you won't be able to see it again!)

Important:

• ✅ Each developer should have their own token
• ✅ Never commit tokens to git
• ✅ Store tokens securely (password manager recommended)

Step 2: Configure npm Authentication

Create or update your .npmrc file in your home directory (~/.npmrc) or project root:

@amenda-app:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN_HERE

Replace YOUR_GITHUB_TOKEN_HERE with the token you copied in Step 1.

Alternative: Set as environment variable:

export GITHUB_TOKEN="your_token_here"
echo "@amenda-app:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=\${GITHUB_TOKEN}" > ~/.npmrc

Step 3: Install the Package

Then install the package:

# Using npm
npm install @amenda-app/cohere-components

# Using yarn
yarn add @amenda-app/cohere-components

# Install required peer dependencies
npm install leaflet lucide-react next-themes react-leaflet styled-jsx

For local development:

{
  "dependencies": {
    "@amenda-app/cohere-components": "file:../cohere-components"
  }
}

⚙️ Configuration

Required Peer Dependencies

Ensure these dependencies are installed in your host application:

• react ^19.0.0
• react-dom ^19.0.0
• next ^15.0.0
• leaflet ^1.9.4
• lucide-react *
• next-themes *
• react-leaflet ^5.0.0
• styled-jsx ^5.1.2

Tailwind CSS Setup

This package is built with Tailwind CSS v4 (CSS-first approach) and includes all necessary Tailwind utility classes pre-compiled in the CSS bundle.

Installation Steps

1. Import the CSS file in your application's main CSS or entry point:

/* app/globals.css or your main CSS file */
@import "tailwindcss";
@import "@amenda-app/cohere-components/styles.css";

/* Your custom theme */
@theme {
  --color-primary: #000000;
}

OR import it in your JavaScript/TypeScript entry point:

// app/layout.tsx or pages/_app.tsx
import '@amenda-app/cohere-components/styles.css';

2. That's it! All Tailwind utilities used by cohere-shared components are already included in the bundle. No additional Tailwind configuration needed.

Important Notes

• ✅ Works with Tailwind v4 (CSS-first, no config file)
• ✅ Pre-compiled CSS - All utilities are bundled, no JIT scanning needed
• ✅ Zero configuration - Just import the CSS file
• ⚠️ If you need custom Tailwind utilities in your own code, you still need to install Tailwind in your project

🚀 Usage

Basic Usage

Import components directly into your application:

'use client'; // Required for Next.js App Router

import { HeroComponent } from '@amenda-app/cohere-components';
import '@amenda-app/cohere-components/styles.css';

export default function MyPage() {
  return (
    <div>
      <HeroComponent
        title="Welcome to the Future"
        subtitle="This component is from the shared library"
        backgroundColor="#000000"
        textColor="#FFFFFF"
      />
    </div>
  );
}

🎨 Multi-Tenant Usage (Recommended)

This component library supports multi-tenant theming out of the box. Perfect for white-label applications or managing multiple brands with the same codebase.

Quick Start with Themes

1. Wrap your app with TenantProvider:

// app/layout.tsx (Next.js 13+ App Router)
import '@amenda-app/cohere-components/styles.css';
import { TenantProvider } from '@amenda-app/cohere-components/context';

export default function RootLayout({ children }) {
  const tenantId = process.env.NEXT_PUBLIC_TENANT_ID || 'h4a';

  return (
    <html lang="en">
      <body>
        <TenantProvider tenantId={tenantId}>
          {children}
        </TenantProvider>
      </body>
    </html>
  );
}

2. Use components with automatic theme:

'use client';

import { useTenant } from '@amenda-app/cohere-components/context';
import { Navbar, Footer } from '@amenda-app/cohere-components';

export default function HomePage() {
  const { tenant } = useTenant();

  return (
    <div>
      <Navbar
        logoHref="/"
        lightLogoSrc={tenant.assets.logo.lightSrc}
        darkLogoSrc={tenant.assets.logo.darkSrc}
        navItems={[
          { href: '/projects', label: 'Projects' },
          { href: '/about', label: 'About' },
        ]}
      />

      <h1 style={{ color: tenant.colors.primary }}>
        Welcome to {tenant.name}
      </h1>

      <Footer logo={tenant.assets.logo} {...footerProps} />
    </div>
  );
}

3. Configure tenant in your environment:

# .env.local
NEXT_PUBLIC_TENANT_ID=h4a

# Available tenants: h4a, tenant2, tenant3

📚 For detailed multi-tenant setup, see USAGE_EXAMPLES.md

Available Themes

• h4a (default) - h4a Architekten theme with blue (#0C4DAF) and magenta (#F8046D)
• tenant2 - Example tenant template
• tenant3 - Example tenant template

Import Themes Directly

import { getTenantTheme, h4aTheme } from '@amenda-app/cohere-components/themes';

// Option 1: Use specific theme
const theme = h4aTheme;

// Option 2: Get theme by ID
const theme = getTenantTheme('h4a');

console.log(theme.colors.primary); // #0C4DAF

For complete examples including:

• Environment variable configuration
• Multi-tenant deployment strategies
• Creating custom themes
• Advanced usage patterns

See USAGE_EXAMPLES.md and MULTI_TENANT_GUIDE.md

SSR (Server-Side Rendering) Compatibility

All components are marked as 'use client' but some may require browser APIs. If you get window is not defined errors:

Option 1: Dynamic Import with No SSR

import dynamic from 'next/dynamic';

const Navbar = dynamic(
  () => import('@amenda-app/cohere-components').then(mod => ({ default: mod.Navbar })),
  { ssr: false }
);

export default function MyPage() {
  return <Navbar {...props} />;
}

Option 2: Use in Client Component

'use client';

import { Navbar } from '@amenda-app/cohere-components';

export default function ClientOnlyPage() {
  return <Navbar {...props} />;
}

📁 Project Structure

cohere-components/
├── src/
│   └── components/     # React components
├── dist/               # Built output
├── package.json
├── tsconfig.json
└── README.md

🛠️ Development & Publishing

Building and Publishing

1. Clone the repository:

git clone https://github.com/amenda-app/cohere-components.git
cd cohere-components

2. Install dependencies:

npm install

3. Make your changes to the components in src/components/

4. Build the package:

npm run build

5. Update the version and create a GitHub release:

npm version patch  # for bug fixes (0.1.0 -> 0.1.1)
npm version minor  # for new features (0.1.0 -> 0.2.0)
npm version major  # for breaking changes (0.1.0 -> 1.0.0)

6. Push the tag to GitHub:

git push && git push --tags

7. Automated release creation - GitHub Actions will automatically:
   • Create a GitHub Release with generated release notes
   • Publish the package to GitHub Packages npm registry
   • No manual steps required! 🎉

Automated Workflows

• Release Creation (.github/workflows/release.yml) - Triggered on version tag push

  • Generates release notes from commits
  • Creates GitHub Release automatically

• Package Publishing (.github/workflows/publish.yml) - Triggered on release creation

  • Builds the package
  • Publishes to GitHub Packages npm registry

Note: You need appropriate permissions in the amenda-app organization to publish updates.

📝 Available Components

The package includes the following components:

• ArchitectureCarousal
• ArticleIntroBlock
• ArticleParagraphBlock
• ArticleQuoteBlock
• ArticleSection
• ArticleSubheadingBlock
• CardGrid
• CarousalAndFeatureLayout
• ContentSection
• CountingSection
• CtaHeading
• FeaturedItemsCarousal
• FeaturedProject
• FilterTabs
• FiveContentLayout
• Footer
• HeadingAndContentBlock
• HeroComponent
• ImageCarousal
• ImageCarouselSection
• ImageComparisonSlider
• ImageGalleryWithStatement
• ImageRowWithText
• ImageSequence
• ImageStrip
• InfiniteCarousal
• InteractiveMap
• JobOpeningsSection
• JobPostingList
• LegalContentSection
• MediaAndTextBlockList
• MediaGridWithCaption
• Navbar
• NavigationTabs
• NewsLayout
• OfficeLocations
• OfficeOverview
• OfficeOverviewTwo
• ProjectFacts
• ProjectGrid
• ProjectHighlightsGrid
• ProjectList
• RecruitmentSection
• TeamCarousal
• TeamGrid
• TextBlockComponent
• TextSectionThree
• TextSectionTwo
• ThreeByThreeGrid
• TimelineSection
• VideoSection

🧪 Testing

This package includes comprehensive test coverage with automated testing via GitHub Actions.

Test Status

Current Coverage:

• ✅ 50 tests across 6 test suites
• ✅ All 51 components tested
• ✅ Automated CI/CD on every push and PR
• ✅ Tested on Node.js 20.x and 22.x

What's Tested

• Component Rendering - All components render without errors
• Props Validation - Components accept correct prop types
• Package Exports - All exports work correctly
• Build Output - Dist files are generated correctly
• TypeScript Types - Type definitions are valid

Running Tests Locally

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the package
npm run build

Test Files

• test/all-components.test.tsx - Basic rendering tests (17 tests)
• test/complex-components.test.tsx - Complex props tests (12 tests)
• test/media-components.test.tsx - Media component tests (10 tests)
• test/component-render.test.tsx - Render validation (3 tests)
• test/package-exports.test.ts - Export validation (4 tests)
• test/dist-build.test.ts - Build verification (4 tests)

🤝 Contributing

1. Create a new component in src/components/
2. Export it from the main entry point
3. Update this README with component documentation
4. Test in a host application before committing

📄 License

[Your License Here]

👥 Maintainers

[Your Team/Contact Information]