PikaCSS Developer Workflow

This skill guides AI agents through development workflows in the PikaCSS monorepo, including architecture decisions, implementation patterns, testing, and release procedures.

Quick Start

Essential Commands

bash

pnpm install          # Install dependencies
pnpm build            # Build all packages
pnpm test             # Run all tests
pnpm typecheck        # Type check all packages
pnpm lint             # Lint and auto-fix

Monorepo Structure

The PikaCSS monorepo uses pnpm workspaces with this layered architecture:

Framework Layer      → @pikacss/nuxt-pikacss
Unplugin Layer       → @pikacss/unplugin-pikacss, @pikacss/vite-plugin-pikacss
Integration Layer    → @pikacss/integration
Core Layer          → @pikacss/core
Official Plugins    → @pikacss/plugin-{icons,reset,typography}

Development Workflow

Before Making Changes

Understand the codebase scope
- Read AGENTS.md for project guidance
- Review existing package responsibilities (see references/ARCHITECTURE.md)
- Check related tests for patterns
- Verify scope of changes with grep/find tools
Follow project conventions
- Code style: TypeScript, camelCase for functions, PascalCase for types
- No non-English content in code/comments/commits
- Use workspace protocol for internal dependencies
- Maintain backward compatibility (unless major version)
Plan changes incrementally
- One logical change per commit
- Build succeeds after each change
- Run tests frequently to verify
- No half-finished features

Implementation Process

For new features:

Identify correct package (see decision tree in references/IMPLEMENTATION-GUIDE.md)
Implement in src/ directory
Write tests in tests/ directory
Update type definitions
Run: pnpm --filter @pikacss/<pkg> test
Verify builds: pnpm build
Check types: pnpm typecheck

For bug fixes:

Locate affected package using grep/read tools
Create reproduction test
Implement fix
Run package-specific tests
Verify full test suite passes
Update docs if behavior changed

Testing Strategy

bash

# Run all tests
pnpm test

# Specific package
pnpm --filter @pikacss/core test

# Watch mode
pnpm --filter @pikacss/core test:watch

# Specific test file
pnpm --filter @pikacss/core test <filename>

Tests follow Vitest patterns and should be placed in:

tests/unit/ - Pure function tests
tests/integration/ - Multi-module tests
tests/e2e/ - End-to-end tests

Release Process

Pre-Release Checklist

Before running pnpm release:

All tests pass: pnpm test
All types correct: pnpm typecheck
All linting passes: pnpm lint
Package exports valid: pnpm publint
Documentation builds: pnpm docs:build
Example code tested and works
AGENTS.md reviewed and updated if major changes
No breaking changes without major version bump

Release Steps

Verify checklist items complete
Run: pnpm release (uses bumpp for versioning)
Publish: pnpm publish:packages
Create GitHub release (automated)

Critical Rules

Never Do These

❌ Manually edit auto-generated files (pika.gen.css, pika.gen.ts, dist/**/*)
❌ Bypass build-time constraints (all pika() args must be static)
❌ Break backward compatibility without major version bump
❌ Skip tests or linting before commit
❌ Use @ts-ignore without clear justification
❌ Run force push to main/master

Always Do These

✅ Make changes atomic (one logical change per commit)
✅ Provide clear commit messages explaining the "why"
✅ Test changes thoroughly before committing
✅ Update documentation when code changes
✅ Review AGENTS.md before major changes
✅ Use pnpm --filter for isolated package work

Commit Message Guidelines

Follow conventional commits format:

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, refactor, test, docs, chore

Example:

feat(core): add support for pseudo-elements

Implement parsing and generation of pseudo-elements
with $ selector syntax. Supports ::before, ::after,
::first-line, ::first-letter patterns.

Closes #123

Common Issues

Build failures

Clear dist: rimraf packages/*/dist
Check tsconfig.json syntax
Verify no circular dependencies

Type errors

Run: pnpm typecheck --filter <package>
Check import paths
Verify tsconfig includes

Test failures in CI

Run full suite locally: pnpm test
Check for timing-dependent tests
Verify environment variables

Next Steps

For detailed implementation patterns and references, see:

references/ARCHITECTURE.md - Package architecture details
references/IMPLEMENTATION-GUIDE.md - Feature/bug fix workflows
references/PLUGIN-PATTERNS.md - Plugin system best practices

Search AI Tools

pikacss-dev

Install this agent skill to your Project

Metadata

SKILL.md