Thrive UI Design System

The Thrive Cart Design System monorepo — a shared UI component library with documentation and an MCP server for AI-powered component generation.

Monorepo Structure

├── apps/
│   ├── design-system-docs/    # Documentation site (Fumadocs + Storybook)
│   └── design-system-mcp/     # MCP server for AI component generation
├── packages/
│   └── ui/                    # @thrivecart/ui — the publishable component library
├── pnpm-workspace.yaml        # pnpm workspace configuration
└── turbo.json                 # Turborepo configuration

Live Preview

• Storybook

Tech Stack

• React 19 — UI framework
• TypeScript — type safety
• Tailwind CSS 4 — styling
• Radix UI — accessible primitives
• Turborepo — monorepo build orchestration
• pnpm — package manager
• tsup — library bundling
• Fumadocs — documentation site
• Storybook — component playground
• MCP SDK — AI-powered design system tooling

Installing @thrivecart/ui as a Dependency

1. Create a GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
2. Click Generate new token (classic)
3. Give it a descriptive name (e.g. thrive-ui-packages)
4. Select the read:packages, write:packages, repo scope
5. Click Generate token
6. Copy the token — you won't be able to see it again

2. Set the NPM_TOKEN Environment Variable

Add the token to your shell profile (~/.bashrc, ~/.zshrc, or equivalent):

export NPM_TOKEN=your_token_here

For permanent use, add it to the .bashrc file:

echo "export NPM_TOKEN=your_token_here" >> ~/.bashrc

Reload your shell:

source ~/.zshrc

3. Add .npmrc to Your Project

Create a .npmrc file in the root of your project with the following content:

@thrivecart:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

${NPM_TOKEN} reads from your environment variable, so this file is safe to commit. Never hardcode the token directly in .npmrc.

4. Install the Package

Install tailwindcss to your project:

pnpm add -D tailwindcss postcss autoprefixer

# npm
npm install @thrivecart/ui

# pnpm
pnpm add @thrivecart/ui

# yarn
yarn add @thrivecart/ui

Using NPM_TOKEN Locally

For local development, set the NPM_TOKEN environment variable so that npm/pnpm/yarn can authenticate with the GitHub Packages registry.

Option A: Export in your current terminal session (temporary)

export NPM_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This lasts only for the current terminal session.

Option B: Add to your shell profile (permanent)

Append the export to your shell config file so it persists across sessions:

# For zsh (macOS default)
echo 'export NPM_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export NPM_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

Option C: Use a .env file (project-scoped)

Create a .env file in your project root:

NPM_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then load it before running install commands:

source .env && pnpm install

Important: Add .env to your .gitignore to avoid committing secrets.

After setting the token, ensure your project has a .npmrc file (see step 3 above), then run your install command as normal.

Using NPM_TOKEN in Deployment (AWS)

In CI/CD and production environments, store the token as a secret and inject it as an environment variable at build time.

AWS CodeBuild

Add NPM_TOKEN as an environment variable in your buildspec.yml:

version: 0.2

env:
  secrets-manager:
    NPM_TOKEN: "arn:aws:secretsmanager:us-east-1:123456789:secret:npm-token:NPM_TOKEN"

phases:
  install:
    commands:
      - npm install
  build:
    commands:
      - npm run build

Alternatively, set it as a plaintext environment variable in the CodeBuild project settings (less secure) or use AWS Systems Manager Parameter Store:

env:
  parameter-store:
    NPM_TOKEN: "/myapp/NPM_TOKEN"

AWS Amplify

1. Go to your Amplify app in the AWS Console
2. Navigate to Hosting > Environment variables
3. Add a new variable: key = NPM_TOKEN, value = your GitHub token
4. Amplify will automatically make it available during the build

AWS EC2 / ECS / Elastic Beanstalk

Set the environment variable in the task definition (ECS), environment properties (Elastic Beanstalk), or user data / shell profile (EC2):

ECS Task Definition (JSON):

{
  "containerDefinitions": [
    {
      "name": "app",
      "environment": [
        {
          "name": "NPM_TOKEN",
          "value": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        }
      ]
    }
  ]
}

For production, use AWS Secrets Manager with secrets instead of environment:

{
  "containerDefinitions": [
    {
      "name": "app",
      "secrets": [
        {
          "name": "NPM_TOKEN",
          "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789:secret:npm-token"
        }
      ]
    }
  ]
}

GitHub Actions (CI/CD)

If you use GitHub Actions for deployment, add NPM_TOKEN as a repository secret and reference it in your workflow:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
      - run: pnpm build

Security best practice: Never hardcode the token in source code, Dockerfiles, or build scripts. Always use secrets management (AWS Secrets Manager, SSM Parameter Store, or GitHub Secrets).

5. Import Styles

Import the CSS in your application entry point (e.g. layout.tsx or main.tsx):

import '@thrivecart/ui/style.css';

6. Use Components

import { Button } from '@thrivecart/ui';

export default function App() {
    return <Button>Click me</Button>;
}

Peer Dependencies

Make sure your project has these peer dependencies installed:

• react ^19.2.3
• react-dom ^19.2.3

Getting Started (Monorepo Development)

Prerequisites

• Node.js 20+
• pnpm (npm install -g pnpm)
• Git

Installation

git clone git@github.com:thrivecart/thrive-ui.git
cd thrive-ui
pnpm install

Development

# Run the UI package + docs app
pnpm dev

# Run only the UI package
pnpm dev:ui

# Run only the docs app
pnpm dev:docs

Build

pnpm build

Available Scripts

Component Development Guidelines

File Naming

• Use kebab-case for all file and directory names
• Main component file matches its directory name

button/
├── button.tsx
├── button.types.ts   # optional — for complex prop interfaces
└── index.ts

Code Style

• Use functional components with TypeScript
• Export components as named exports
• Keep components focused and single-responsibility
• Extract complex logic into hooks

Import Order

// 1. External dependencies
import { useState } from 'react';

// 2. Internal packages
import { cn } from '@thrivecart/ui';

// 3. Local imports
import { ButtonProps } from './button.types';