heroui-components
Add or customize HeroUI components in the web application. Use when implementing new UI features with HeroUI design system or updating compo
Open source Repository Open in the app JSON README (API)
About
Add or customize HeroUI components in the web application. Use when implementing new UI features with HeroUI design system or updating component styling.
Details
- Kind
- Agent skills
- Topic
- Media, design & games
- Publisher
- sgcarstrends
- Origin
- majiayu
- Category
- ferramentas
- Stars
- 13
- Forks
- 2
- Open pull requests
- 11
- Last push
- 2026-09-05T03:14:00Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-09-01 17:08:45
- Updated
- 2026-09-01 17:08:45
- Origin id
sgcarstrends/sgcarstrends/.claude/skills/heroui-components@main
README
# MotorMetrics
[](https://opensource.org/licenses/MIT)
## Overview
This monorepo provides a complete platform for MotorMetrics, tracking Singapore's car registration statistics and Certificate of Entitlement (COE) data. The system includes:
- **Web Application**: Next.js 16 frontend with Cache Components, co-located route components, enhanced homepage featuring latest COE results, interactive charts, analytics, AI-generated blog content, and integrated admin interface at `/admin` path. Also hosts the data updater workflows.
- **Integrated Data Updater**: Vercel WDK workflow-based system for fetching and processing LTA data (consolidated into web application)
- **LLM Blog Generation**: Automated blog post creation using Vercel AI SDK with Google Gemini for market insights (runs within web workflows)
- **Social Media Integration**: Automated posting to Discord, LinkedIn, Telegram, and Twitter with trackable redirect routes (triggered by web workflows)
- **MCP Server**: Published npm package for blog post CRUD operations via Claude Code
- **Documentation Site**: Fumadocs-powered documentation for technical guides and API reference
- **Infrastructure**: Vercel deployment with automatic CI/CD
## System Overview
```mermaid
graph TB
subgraph "Frontend & Workflows"
WEB[Web App<br/>Next.js 16]
BLOG[Blog Posts<br/>AI Generated]
WORKFLOWS[Data Workflows<br/>Vercel WDK]
LLM[Vercel AI SDK<br/>Blog Generation]
end
subgraph "Data Layer"
DB[(PostgreSQL<br/>Neon)]
REDIS[(Redis Cache<br/>Upstash)]
end
subgraph "External APIs"
LTA[LTA DataMall<br/>Gov Data]
end
subgraph "Social Platforms"
DISCORD[Discord]
LINKEDIN[LinkedIn]
TWITTER[Twitter]
TELEGRAM[Telegram]
end
subgraph "Infrastructure"
VERCEL[Vercel<br/>Edge Network]
end
WEB --> WORKFLOWS
WEB --> DB
WEB --> REDIS
WORKFLOWS --> LTA
WORKFLOWS --> DB
WORKFLOWS --> LLM
LLM --> BLOG
WORKFLOWS --> DISCORD
WORKFLOWS --> LINKEDIN
WORKFLOWS --> TWITTER
WORKFLOWS --> TELEGRAM
WEB --> VERCEL
classDef frontend fill:#e1f5fe
classDef backend fill:#f3e5f5
classDef data fill:#e8f5e8
classDef external fill:#fff3e0
classDef social fill:#fce4ec
classDef infra fill:#f1f8e9
class WEB,BLOG,WORKFLOWS,LLM frontend
class DB,REDIS data
class LTA external
class DISCORD,LINKEDIN,TWITTER,TELEGRAM social
class VERCEL infra
```
## Project Structure
```
motormetrics/
├── apps/
│ ├── docs/ # Fumadocs documentation site (Next.js 16)
│ │ ├── content/ # MDX documentation files
│ │ ├── src/app/ # Next.js App Router with docs layout
│ │ └── src/lib/ # Fumadocs source adapter and shared config
│ ├── mcp/ # MCP server for blog post CRUD (published to npm)
│ │ └── src/ # TypeScript server implementation
│ ├── web/ # Next.js 16 frontend application with integrated workflows
│ │ ├── src/app/ # Next.js App Router pages and layouts
│ │ │ ├── (social)/ # Social media redirect routes with UTM tracking
│ │ │ ├── admin/ # Integrated admin interface for content management
│ │ │ ├── blog/ # Blog pages with AI-generated content
│ │ │ └── api/workflows/ # Vercel WDK workflow endpoints
│ │ ├── src/lib/workflows/ # Data updater workflows and social media integration
│ │ ├── src/queries/ # Data fetching queries (cars, COE, logos) with comprehensive tests
│ │ ├── src/actions/ # Server actions (maintenance tasks)
│ │ ├── src/components/ # React components with comprehensive tests
│ │ ├── src/utils/ # Web-specific utility functions
│ │ └── src/config/ # Database, Redis, and platform configurations
├── packages/
│ ├── ai/ # AI-powered blog generation package
│ │ ├── src/generate-post.ts # 2-step blog generation
│ │ ├── src/schemas.ts # Zod schemas for structured output
│ │ └── src/instrumentation.ts # Langfuse telemetry
│ ├── database/ # Database schema and migrations (Drizzle ORM)
│ │ ├── src/schema/ # Schema definitions for all tables
│ │ └── migrations/ # Database migration files
│ ├── logos/ # Car logo management with Vercel Blob storage
│ ├── types/ # Shared TypeScript types
│ └── utils/ # Shared utility functions and Redis configuration
```
## Technologies
- **Frontend**: Next.js 16.1 with Cache Components, React 19.2, TypeScript 5.8
- **UI Library**: HeroUI v3 (`@heroui/react`) and HeroUI Pro (`@heroui-pro/react`) on Tailwind CSS v4
- **Styling**: Tailwind CSS v4.1 with custom configuration
- **Backend**: Node.js 22, TypeScript with strict mode
- **API Framework**: Hono with OpenAPI documentation
- **Database**: Neon Serverless PostgreSQL with Drizzle ORM
- **Caching**: Upstash Redis for API responses and analytics
- **Infrastructure**: Vercel with automatic deployments
- **Scheduling**: Vercel WDK Workflows with Vercel Cron for data processing
- **LLM Integration**: Vercel AI SDK with Google Gemini for blog content generation
- **Package Management**: pnpm v11.0.0 workspace with catalog for centralised dependency management
- **Build Tools**: Turbo v2.6.3 for monorepo orchestration, Turbopack for fast development builds
- **Testing**: Vitest v4.0.15 (unit), Playwright (E2E) with comprehensive coverage
- **Linting & Formatting**: Biome v2.3.0 for consistent code style, formatting, and import organisation
## Documentation
For developers working on this codebase, detailed component-specific guidance is available:
- **[Root CLAUDE.md](CLAUDE.md)** - Overall project guidance and conventions
- **[Web Application](apps/web/CLAUDE.md)** - Next.js development, HeroUI components, blog features, and data updater workflows
- **[AI Package](packages/ai/CLAUDE.md)** - AI-powered blog generation with Vercel AI SDK and Google Gemini
- **[Database Package](packages/database/CLAUDE.md)** - Schema management, migrations, and TypeScript integration
- **[Logos Package](packages/logos/CLAUDE.md)** - Car logo management with Vercel Blob storage
### Product Documentation
Forward-looking product proposals and opportunity assessments are available in
the [`docs/product/`](docs/product/) directory:
- **[Mobile App Opportunity](docs/product/2026-07-29-mobile-app-opportunity.md)** -
Product thesis and validation path for a personalised vehicle companion
- **[Advertiser Dashboard](docs/product/2026-04-05-advertiser-dashboard-design.md)** -
Design proposal for a self-serve advertising platform
### Architecture Documentation
System architecture diagrams are available in the `docs/` directory:
- **[docs/architecture/](docs/architecture/)** - Architecture documentation with Mermaid diagrams
- **[docs/diagrams/](docs/diagrams/)** - Source Mermaid diagram files
## Getting Started
### Prerequisites
- Node.js >= 22
- pnpm v11.0.0
### Installation
```bash
# Clone the repository
git clone https://github.com/motormetrics/motormetrics.git
cd motormetrics
# Install dependencies
pnpm install
```
#### Dependency Management
This project uses **pnpm catalog** for centralised dependency version management. Shared dependencies (React, Next.js, TypeScript, testing tools, etc.) are defined in `pnpm-workspace.yaml` and referenced by workspace packages using the `catalog:` protocol.
**Key catalog packages:**
- React ecosystem: `react` (^19.2.3), `react-dom` (^19.2.3), `next` (^16.1.0)
- TypeScript & types: `typescript` (^5.8.3), `@types/node` (^22.16.4), `@types/react` (^19.2.0), `@types/react-dom` (^19.2.0)
- Testing tools: `vitest` (^4.0.15), `@vitest/coverage-v8` (^4.0.15)
- AI & LLM: `ai`, `@ai-sdk/gateway`, `@ai-sdk/openai`, `@langfuse/otel`
- Utilities: `date-fns` (^3.6.0), `zod` (^4.1.13), `sonner` (2.0.7)
**Root-level dependencies** (not in catalog):
- Build tools: `turbo` (^2.6.3)
- Code quality: `@biomejs/biome` (2.3.0), `husky` (^9.1.7), `lint-staged` (^16.1.5)
- Release management: `semantic-release` (^24.0.0)
This ensures version consistency across all workspace packages and simplifies dependency upgrades.
### Development
```bash
# Development
pnpm dev # Run all development servers
pnpm dev:web # Web application only
cd apps/web && pnpm dev # Web application development
# Build
pnpm build # Build all applications
pnpm build:web # Build web application only
# Testing
pnpm test # Run all unit tests
pnpm test:watch # Run tests in watch mode
pnpm test:coverage # Run tests with coverage
pnpm test:web # Run web tests only
cd apps/web && pnpm test # Web tests only
# E2E Testing (Web App)
pnpm -F /web test:e2e # Run Playwright E2E tests
pnpm -F /web test:e2e:ui # Run E2E tests with Playwright UI
# Code Quality
pnpm lint # Run Biome linting on all packages
pnpm format # Run Biome formatting on all packages
pnpm lint:web # Lint web application only
cd apps/web && pnpm lint # Lint web application only
# Database
pnpm db:migrate # Run database migrations
pnpm db:migrate:check # Check migration status
pnpm db:generate # Generate new migrations
pnpm db:push # Push schema changes
```
### Deployment
Deployment is handled automatically by Vercel:
- **Production**: Push to `main` branch triggers automatic deployment
- **Preview**: Pull requests get automatic preview deployments
## API Endpoints
### Web Application Workflows (apps/web)
**Workflow Endpoints (Vercel Cron Triggered):**
- `GET /api/workflows/cars` - Car data processing workflow
- `GET /api/workflows/coe` - COE data processing workflow
- `GET /api/workflows/deregistrations` - Vehicle deregistration processing workflow
## Repo Activity
## License
[MIT](LICENSE)