Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ecomfe/tempad-dev/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The plugins package (@tempad-dev/plugins) is a public SDK that provides types, hooks, and helpers for plugin authors to customize TemPad Dev’s code generation behavior.
Location: packages/plugins/
NPM Package: @tempad-dev/plugins
Repository: https://github.com/ecomfe/tempad-dev
Responsibilities
- Stable, documented plugin APIs
- Types and helpers safe for external users
- Transform hooks for code generation
- Maintaining README examples
Tech Stack
- Language: TypeScript
- Build Tool: tsdown
- Output: ESM + TypeScript declarations
Directory Structure
packages/plugins/
├── src/
│ └── index.ts # Public exports (types, hooks, helpers)
├── tests/ # Test files
├── README.md # English documentation
├── README.zh-Hans.md # Chinese documentation
├── tsdown.config.ts # Build configuration
└── package.json
Key Commands
Building
# From root
pnpm build:plugins
# From package directory
pnpm -C packages/plugins build
# Or with filter
pnpm --filter @tempad-dev/plugins build
dist/index.js - ESM exportdist/index.d.ts - TypeScript types
Testing
# Run tests
pnpm -C packages/plugins test:run
# With coverage
pnpm -C packages/plugins test:coverage
# Watch mode
pnpm -C packages/plugins test
Quality Checks
# Typecheck
pnpm -C packages/plugins typecheck
# Lint
pnpm -C packages/plugins lint
pnpm -C packages/plugins lint:fix
# Format
pnpm -C packages/plugins format
pnpm -C packages/plugins format:check
Publishing
# From root
pnpm npm:plugins
# Manually
pnpm -C packages/plugins publish --access public
build runs automatically via prepublishOnly
Public API
Transform Hooks
Plugins provide transform hooks for customizing code generation:
export type TransformOptions = {
// Transform pixel values
transformPx?: (value: number) => number
// Transform CSS variable names
transformVariable?: (name: string) => string
// Transform color values
transformColor?: (color: string) => string
// ... more hooks
}
Example Usage
import type { TransformOptions } from '@tempad-dev/plugins'
const options: TransformOptions = {
transformPx: (px) => px / 16, // Convert to rem
transformVariable: (name) => `var(--${name})`
}
Type Exports
All public types are exported from src/index.ts:
export type TransformOptions = { /* ... */ }
export type CodegenContext = { /* ... */ }
export type PluginHooks = { /* ... */ }
Code Style Guidelines
Additive API Changes
Good: Add optional fields
export type TransformOptions = {
transformPx?: (value: number) => number
transformVariable?: (name: string) => string
transformColor?: (color: string) => string // New optional field
}
// Bad: Removed existing hook
export type TransformOptions = {
transformVariable?: (name: string) => string
// transformPx removed - BREAKING
}
Always Update README
When public types change, update both:
README.md (English)README.zh-Hans.md (Chinese)
Testing Strategy
Coverage Focus
Coverage focused on src/index.ts:
pnpm -C packages/plugins test:coverage
Test Files
Location: tests/
Pattern: *.test.ts (Node runtime only)
Example Test
import { describe, it, expect } from 'vitest'
import type { TransformOptions } from '../src/index'
describe('TransformOptions', () => {
it('allows optional transform hooks', () => {
const options: TransformOptions = {
transformPx: (px) => px / 16
}
expect(options.transformPx?.(16)).toBe(1)
})
})
Boundaries and Constraints
Never Introduce Extension Internals
Do not expose extension-specific concepts:
// Bad: Extension-specific type
export type MCPToolContext = { /* ... */ }
// Good: Generic, public type
export type TransformContext = { /* ... */ }
No Runtime Dependencies
Do not add runtime dependencies without approval. The package should be lightweight.
No Breaking Changes
Treat every change as public-facing. Do not make breaking changes unless explicitly planned.
Verification Checklist
Always Run
pnpm -C packages/plugins typecheck
pnpm -C packages/plugins lint
pnpm -C packages/plugins test:run
README Updates
When changing public types:
- Update
README.md examples
- Update
README.zh-Hans.md examples
- Verify code examples compile
Coverage Check
pnpm -C packages/plugins test:coverage
Publishing Workflow
- Update version in
package.json
- Update README if API changed
- Build:
pnpm -C packages/plugins build
- Verify:
pnpm -C packages/plugins typecheck
pnpm -C packages/plugins test:run
- Publish:
Pre-publish hook runs build automatically.
Package Configuration
Exports
From package.json:
{
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
}
}
Files
Only dist/ and README.md are published:
{
"files": [
"dist",
"README.md"
]
}
Versioning
Follow semantic versioning:
- Patch: Bug fixes, documentation updates
- Minor: New optional fields, backward-compatible additions
- Major: Breaking changes, removed/renamed fields
Related Documentation
In source repo:
- Testing architecture:
docs/testing/architecture.md
In this site:
