tpmjs/README.md

TPMJS

TPMJS is a registry for discovering AI tools published to npm.

Browse, search, and find tools at tpmjs.com. Publish your tool by adding the tpmjs keyword to your package.json—it appears in the registry within 15 minutes.

Why TPMJS?

• Discover tools - Search and browse AI tools by category, quality score, and popularity
• Publish easily - Add one keyword to package.json, publish to npm, done
• Quality metrics - Tools are scored based on documentation, downloads, and metadata completeness
• Agent integration - Optional SDK for agents to search and execute tools at runtime

Quick Start

Publishing a Tool

npx @tpmjs/create-basic-tools

Or add manually to your package.json:

{
  "keywords": ["tpmjs"],
  "tpmjs": {
    "category": "text-analysis"
  }
}

Publish to npm and your tool appears on tpmjs.com within 15 minutes.

See HOW_TO_PUBLISH_A_TOOL.md for the full guide.

For AI Agents (Optional)

Agents can search and execute tools from the registry:

npm install @tpmjs/registry-search @tpmjs/registry-execute

import { registrySearchTool } from '@tpmjs/registry-search';
import { registryExecuteTool } from '@tpmjs/registry-execute';

// Add to your agent's tools
const tools = [registrySearchTool, registryExecuteTool];

---

Monorepo Structure

apps/
  web/          - Next.js 16 App Router application
packages/
  config/       - Shared configurations (Biome, ESLint, Tailwind, TypeScript)
  ui/           - React component library (.ts-only, no barrels)
  utils/        - Utility functions
  types/        - Shared TypeScript types
  env/          - Zod environment schema loader
  test/         - Vitest shared configuration
  mocks/        - MSW mock server
  storybook/    - Storybook documentation

Getting Started

Prerequisites

• Node.js >= 22 (LTS)
• pnpm >= 8
• nvm (recommended for Node version management)

Installation

pnpm install

Development

# Run all apps in development mode
pnpm dev

# Run specific app
pnpm --filter @tpmjs/web dev
pnpm --filter @tpmjs/storybook dev

Building

# Build all packages and apps
pnpm build

# Build specific package
pnpm --filter @tpmjs/ui build

Testing

# Run all tests
pnpm test

# Run tests in watch mode with UI
pnpm test:ui

Linting & Formatting

# Lint all packages
pnpm lint

# Format all files
pnpm format

# Check formatting
pnpm format:check

Quality Gates

# Check architecture/dependency rules
pnpm check-architecture

# Find unused code and dependencies
pnpm find-deadcode

# Check type coverage
pnpm type-coverage

See QUALITY-GATES.md for details.

Component Usage

Components are imported directly without barrel exports:

import { Button } from '@tpmjs/ui/Button/Button';
import { Card, CardHeader } from '@tpmjs/ui/Card/Card';

Important: All UI components use .ts extension (not .tsx) and use createElement instead of JSX.

Publishing Workflow

1. Create Changesets

After making changes to publishable packages:

pnpm changeset

Follow the prompts to describe your changes and select which packages are affected.

2. Version Packages

When ready to release:

pnpm changeset:version

This updates package versions and generates CHANGELOGs.

3. Publish to npm

pnpm changeset:publish

This builds and publishes all packages with changesets to npm.

4. Push to GitHub

git push --follow-tags

Published Packages

• @tpmjs/ui - React component library
• @tpmjs/utils - Utility functions
• @tpmjs/types - TypeScript types
• @tpmjs/env - Environment schema loader

Deployment

The project is configured to only deploy to Vercel when all CI checks pass. This ensures production always has high-quality, tested code.

CI Checks:

• Linting & formatting
• Type checking
• Tests
• Production build
• Architecture validation
• Dead code detection

See DEPLOYMENT.md for full configuration details.

Module Boundaries

ESLint enforces module boundaries:

• Apps can import from published packages only
• Packages cannot import from apps
• No barrel exports (index.ts) allowed
• Direct imports required: @tpmjs/ui/Button/Button

Architecture Decisions

Why .ts-only Components?

Using .ts instead of .tsx for React components:

• Enforces explicit createElement calls
• Makes React's runtime nature more visible
• Prevents JSX spreading anti-patterns
• Better for code generation and tooling

Why No Barrel Exports?

• Clearer dependency graphs
• Better tree-shaking
• Explicit imports show what's actually used
• Prevents circular dependencies

Why Biome + ESLint?

• Biome: Fast formatting and basic linting
• ESLint: Semantic rules (module boundaries, TypeScript strictness)
• Each tool focuses on what it does best

Scripts Reference

• dev - Start development servers
• build - Build all packages
• test - Run tests
• test:ui - Run tests with UI
• lint - Lint code
• format - Format code with Biome
• format:check - Check formatting
• type-check - TypeScript type checking
• type-coverage - Check type coverage (no implicit any)
• check-architecture - Validate dependency rules
• find-deadcode - Find unused code/dependencies
• clean - Remove build artifacts
• changeset - Create a changeset
• changeset:version - Version packages
• changeset:publish - Publish to npm

License

MIT