Contributing to PikaCSS

Thank you for your interest in contributing to PikaCSS! This guide will help you get started.

Ways to Contribute

There are many ways to contribute to PikaCSS:

🐛 Report bugs - Found a bug? Open an issue
✨ Suggest features - Have an idea? Start a discussion
📖 Improve documentation - Fix typos, add examples, clarify explanations
🔧 Fix issues - Browse open issues and submit PRs
🎨 Create plugins - Share your custom plugins with the community
💬 Help others - Answer questions in Discussions
🌟 Spread the word - Write blog posts, create tutorials, share on social media

Development Setup

Prerequisites

Node.js 18+ (LTS recommended)
pnpm 10.24.0+
Git

Getting Started

Fork the repository
Visit pikacss/pikacss and click "Fork"

Clone your fork

bash

git clone https://github.com/YOUR_USERNAME/pikacss.git
cd pikacss

Install dependencies
bash
```
pnpm install
```
Set up git hooks
bash
```
pnpm prepare
```

Create a branch

bash

git checkout -b feat/my-feature
# or
git checkout -b fix/my-bugfix

Project Structure

pikacss/
├── packages/
│   ├── core/              # Core engine
│   ├── integration/       # Build-time integration
│   ├── unplugin/          # Universal plugin
│   ├── vite/              # Vite plugin
│   ├── nuxt/              # Nuxt module
│   ├── plugin-icons/      # Icons plugin
│   ├── plugin-reset/      # CSS reset plugin
│   └── plugin-typography/ # Typography plugin
├── docs/                  # Documentation site
├── demo/                  # Demo application
└── scripts/               # Build scripts

Development Workflow

Building

bash

# Build all packages
pnpm build

# Build specific package
pnpm --filter @pikacss/core build

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

Testing

bash

# Run all tests
pnpm test

# Test specific package
pnpm --filter @pikacss/core test

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

# Coverage
pnpm test:coverage

Type Checking

bash

# Check all packages
pnpm typecheck

Linting

bash

# Lint and auto-fix
pnpm lint

Documentation

bash

# Start docs dev server
pnpm docs:dev

# Build docs
pnpm docs:build

# Preview built docs
pnpm docs:preview

Making Changes

Code Style

PikaCSS uses ESLint with @antfu/eslint-config. The linter runs automatically on commit via lint-staged.

Key conventions:

Use TypeScript for all code
Use tabs for indentation (configured in ESLint)
Follow existing code style
Add JSDoc comments for public APIs
Write tests for new features

Commit Messages

We follow Conventional Commits:

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

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
perf: Performance improvements
test: Test changes
chore: Build process or tooling changes
ci: CI/CD changes

Examples:

bash

feat(core): add support for container queries

fix(unplugin): resolve HMR issue in webpack

docs(guide): add migration guide from tailwind

test(integration): add tests for nuxt module

Adding Features

Check existing issues - Someone might already be working on it
Create an issue - Discuss the feature first (for large changes)
Write tests - Add tests before or alongside implementation
Update docs - Document new features thoroughly
Add types - Ensure full TypeScript support
Create PR - Submit for review

Fixing Bugs

Create a test - Add a failing test that reproduces the bug
Fix the bug - Make the test pass
Check side effects - Ensure fix doesn't break other features
Update docs - If behavior changed
Create PR - Submit for review

Adding Tests

Tests are written with Vitest:

typescript

// packages/core/tests/my-feature.test.ts
import { createEngine, defineEngineConfig } from '@pikacss/core'
import { describe, expect, it } from 'vitest'

describe('myFeature', () => {
  it('should work correctly', async () => {
    const engine = await createEngine(defineEngineConfig({}))
    
    const result = await engine.use({ color: 'red' })
    
    expect(result).toBeDefined()
  })
})

Creating Plugins

See Plugin Development Guide for detailed instructions.

Use the scaffolding tool:

bash

pnpm newplugin my-plugin

This creates:

packages/plugin-my-plugin/ directory
Package configuration
Basic plugin structure
Tests setup

Pull Request Process

Before Submitting

[ ] Tests pass: pnpm test
[ ] Types are correct: pnpm typecheck
[ ] Linter passes: pnpm lint
[ ] Docs are updated (if needed)
[ ] AGENTS.md is updated (if major changes)
[ ] All commits follow convention
[ ] Branch is up to date with main

Submitting

Push your branch
bash
```
git push origin feat/my-feature
```
Create Pull Request
- Go to your fork on GitHub
- Click "Compare & pull request"
- Fill out the PR template
- Link related issues

PR Title Format

Use conventional commit format:

feat(core): add new feature
fix(unplugin): resolve bug

PR Description
- Describe what changed and why
- Include screenshots/demos (if applicable)
- List breaking changes (if any)
- Reference related issues

Review Process

Automated checks - CI runs tests, linting, type checking
Code review - Maintainers review your changes
Feedback - Address any requested changes
Approval - Once approved, PR will be merged
Release - Changes included in next release

Issue Guidelines

Reporting Bugs

When reporting bugs, include:

Description - Clear description of the bug
Reproduction - Minimal code to reproduce
Expected behavior - What should happen
Actual behavior - What actually happens
Environment:
- PikaCSS version
- Node.js version
- Build tool and version
- Framework and version
- OS

Example:

markdown

## Description
Styles are not applied when using shortcuts

## Reproduction
\`\`\`typescript
// pika.config.ts
shortcuts: [
  ['btn', { padding: '1rem' }]
]

// Component
pika('btn') // No styles applied
\`\`\`

## Expected
Button should have 1rem padding

## Actual
No padding applied

## Environment
- PikaCSS: 0.0.37
- Vite: 5.0.0
- Node: 18.17.0
- OS: macOS 13.5

Suggesting Features

When suggesting features:

Use case - Describe the problem you're solving
Proposal - Describe your solution
Alternatives - Other solutions you considered
Examples - Show code examples

Documentation Contributions

Documentation is just as important as code!

Types of Documentation

Guides - Step-by-step tutorials
API Reference - Detailed API docs
Examples - Practical code examples
Troubleshooting - Common issues and solutions
Blog posts - External tutorials and guides

Documentation Style

Use clear, simple language
Include code examples
Show both good and bad patterns
Add warnings for edge cases
Keep examples minimal and focused

Updating Docs

Docs are in docs/ directory and built with VitePress:

bash

# Start dev server
pnpm docs:dev

# Edit markdown files in docs/
# Changes are hot-reloaded

# Build to verify
pnpm docs:build

Community Guidelines

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Assume good intentions
No harassment or discrimination

Getting Help

GitHub Discussions - Ask questions, share ideas
GitHub Issues - Report bugs, request features
Documentation - Check docs first
Search - Someone might have asked before

Helping Others

Be patient and welcoming
Point to relevant documentation
Provide working examples
Explain the "why" not just the "how"

Recognition

Contributors are recognized in:

GitHub contributors list
Release notes (significant contributions)
Documentation (plugin authors, tutorial creators)

Release Process

Releases are managed by maintainers:

Run tests and checks: pnpm test && pnpm typecheck && pnpm lint
Build all packages: pnpm build
Verify exports: pnpm publint
Build docs: pnpm docs:build
Version bump: pnpm release (uses bumpp)
Publish to npm: pnpm publish:packages
Update changelog
Create GitHub release

Questions?

Check FAQ
Ask in Discussions
Read Troubleshooting

Thank You!

Every contribution, no matter how small, makes PikaCSS better. Thank you for being part of the community! 🎉

Contributing to PikaCSS ​

Ways to Contribute ​

Development Setup ​

Prerequisites ​

Getting Started ​

Project Structure ​

Development Workflow ​

Building ​

Testing ​

Type Checking ​

Linting ​

Documentation ​

Making Changes ​

Code Style ​

Commit Messages ​

Adding Features ​

Fixing Bugs ​

Adding Tests ​

Creating Plugins ​

Pull Request Process ​

Before Submitting ​

Submitting ​

Review Process ​

Issue Guidelines ​

Reporting Bugs ​

Suggesting Features ​

Documentation Contributions ​

Types of Documentation ​

Documentation Style ​

Updating Docs ​

Community Guidelines ​

Code of Conduct ​

Getting Help ​

Helping Others ​

Recognition ​

Release Process ​

Questions? ​

Thank You! ​

Contributing to PikaCSS

Ways to Contribute

Development Setup

Prerequisites

Getting Started

Project Structure

Development Workflow

Building

Testing

Type Checking

Linting

Documentation

Making Changes

Code Style

Commit Messages

Adding Features

Fixing Bugs

Adding Tests

Creating Plugins

Pull Request Process

Before Submitting

Submitting

Review Process

Issue Guidelines

Reporting Bugs

Suggesting Features

Documentation Contributions

Types of Documentation

Documentation Style

Updating Docs

Community Guidelines

Code of Conduct

Getting Help

Helping Others

Recognition

Release Process

Questions?

Thank You!