Contributing to kstyled

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to kstyled.

Development Setup

Prerequisites

Node.js >= 18
pnpm >= 8 (or bun >= 1.0)
Git

Getting Started

Fork and clone the repository

git clone https://github.com/hyodotdev/kstyled.git
cd kstyled

Install dependencies

Using pnpm (recommended):
```
pnpm install
```
Using bun:
```
bun install
```
Build all packages
```
pnpm build
# or
bun run build
```
Run the example app
```
pnpm dev
# or
bun run dev
```

Project Structure

kstyled/
├── packages/
│   ├── kstyled/ # Runtime library (styled, ThemeProvider, etc.)
│   ├── babel-plugin-kstyled/ # Babel transformation plugin
│   ├── example/               # Expo example app for testing
│   └── docs/                  # Documentation (Docusaurus)
├── pnpm-workspace.yaml        # pnpm workspace configuration
├── turbo.json                 # Turborepo build pipeline
└── package.json               # Root package.json

Development Workflow

Making Changes

Create a new branch for your feature/fix:

git checkout -b feature/your-feature-name

Make your changes in the appropriate package:
- Runtime changes: packages/kstyled/src/
- Babel plugin changes: packages/babel-plugin-kstyled/src/
- Example app changes: packages/example/app/
- Documentation: packages/docs/docs/
Build and test your changes:
```
pnpm build
pnpm typecheck
pnpm lint
```
Test in the example app:
```
pnpm dev
```

Running the Example App

Quick Start

The simplest way to start developing:

# Start Metro bundler
pnpm dev

# In a new terminal, run the platform you want:
pnpm --filter example android   # Android
pnpm --filter example ios        # iOS (Mac only)
pnpm --filter example web        # Web

Important: Metro Bundler

One Metro instance serves all platforms (Android, iOS, Web). Start Metro once, then connect each platform to it.

┌─────────────────────────────────┐
│   Metro Bundler (port 8081)     │
└─────────────────────────────────┘
         │
    ┌────┴────┬────────┬────────┐
    │         │        │        │
  Android    iOS     Web    ...

VSCode Development

Use the pre-configured launch tasks:

Cmd+Shift+D (Run and Debug panel)
Select "Run Android" or "Run iOS" - Metro starts automatically
After Metro is running, select "Run Web" to open browser (reuses Metro)

Port Conflicts

If you get "Port 8081 already in use":

# Check what's using the port
lsof -i:8081

# Kill the process
lsof -ti:8081 | xargs kill -9

# Restart Metro
pnpm dev

Code Style

Use TypeScript for all source code
Follow existing code style (use ESLint)
Add JSDoc comments for public APIs
Write descriptive commit messages

Type Checking

All packages use TypeScript. Run type checking with:

pnpm typecheck

Linting

We use ESLint for code quality. Run linting with:

pnpm lint

Testing

Manual Testing

The example app (packages/example/) is the primary way to test changes:

Make changes to kstyled or babel-plugin-kstyled
Rebuild: pnpm build
Run example: pnpm dev
Test your changes in the Expo app

Adding Test Cases

When adding new features, please add examples to the demo app:

Add new screens to packages/example/app/
Demonstrate the feature with clear UI
Add comments explaining the feature

Pull Request Process

Update documentation - Update README.md if you're adding new features
Test thoroughly - Ensure your changes work in the example app
Write clear PR description - Explain what and why
Link related issues - Reference any related issue numbers

PR Title Format

Use conventional commit format:

feat: add variants API
fix: resolve theme context issue
docs: update installation guide
perf: optimize style merging
refactor: simplify CSS parser
test: add benchmark tests

Package Scripts

Root Level

pnpm build - Build all packages
pnpm dev - Run example app
pnpm typecheck - Type check all packages
pnpm lint - Lint all packages
pnpm clean - Clean all build artifacts

Package Level

Each package has its own scripts:

cd packages/kstyled
pnpm build       # Build this package
pnpm typecheck   # Type check
pnpm lint        # Lint
pnpm test        # Run tests (if available)

Turborepo

This project uses Turborepo for build orchestration. Key concepts:

Task dependencies - build tasks depend on dependencies being built first
Caching - Build outputs are cached for speed
Parallel execution - Independent tasks run in parallel

Bun and pnpm Support

Both package managers are fully supported:

pnpm (Primary)

pnpm install
pnpm build
pnpm dev

Bun (Alternative)

bun install
bun run build
bun run dev

Note: The lockfiles for both are committed:

pnpm-lock.yaml for pnpm
bun.lockb for bun

Release Process

(For maintainers)

Publishing a New Version

We support two methods for publishing: GitHub Actions (Recommended) and Manual.

Method 1: GitHub Actions (Recommended)

The easiest way to publish is using the automated GitHub Actions workflow:

Go to GitHub Actions

Navigate to: https://github.com/hyodotdev/kstyled/actions/workflows/publish.yml
Run workflow
- Click "Run workflow"
- Select branch: main
- Choose version bump type:
  - patch - Bug fixes (0.3.0 → 0.3.1)
  - minor - New features (0.3.0 → 0.4.0)
  - major - Breaking changes (0.3.0 → 1.0.0)
- Optional: Check "Dry run" to test without publishing
Wait for completion

The workflow will automatically:
- ✅ Build all packages
- ✅ Run type checking and tests
- ✅ Bump versions in both packages
- ✅ Commit and push changes
- ✅ Publish to npm (with OIDC authentication)
- ✅ Create git tag
- ✅ Create GitHub Release with auto-generated notes
Verify

Check that:
- New version appears on npm
- GitHub Release is created
- Git tag is pushed

Note: The workflow uses OpenID Connect (OIDC) for npm authentication, so no NPM_TOKEN is needed.

Method 2: Manual Publishing

If you need to publish manually:

Update package versions

Use the version scripts to automatically bump versions in both packages:
```
pnpm version:patch  # 0.3.0 → 0.3.1 (bug fixes)
pnpm version:minor  # 0.3.0 → 0.4.0 (new features)
pnpm version:major  # 0.3.0 → 1.0.0 (breaking changes)
```
This updates both kstyled and babel-plugin-kstyled at once using the custom scripts/bump-version.js script.
Build and test everything
```
pnpm build && pnpm typecheck && pnpm test
```
Make sure all checks pass with 0 errors.

Commit version changes

git add packages/*/package.json
git commit -m "chore: release v0.3.1"
git tag v0.3.1

Verify npm login

npm whoami
# Should display your npm username

If not logged in:

npm login

Test publish (dry-run)
```
pnpm publish:dry
```
This shows what would be published without actually publishing. Check:
- Package sizes look reasonable
- File list is correct
- No unexpected files included
Publish to npm

Option A: Stable Release (latest tag)
```
pnpm publish:packages
```
For provenance (recommended):
```
pnpm publish:packages --provenance
```
This publishes both kstyled and babel-plugin-kstyled to npm with public access as the latest version.

Option B: Beta/Preview Release (next tag)
```
pnpm publish:packages --tag next
```
Use this for:
- Testing major changes before stable release
- Preview releases for early adopters
- Release candidates (e.g., 0.3.0-rc.1)

Push changes and tags

git push origin main
git push origin v0.3.1

Create GitHub Release (optional)

Go to: https://github.com/hyodotdev/kstyled/releases/new
- Select the tag you just pushed
- Generate release notes automatically
- Publish release

Verify publication

npm view kstyled version
npm view babel-plugin-kstyled version
# Both should show the new version

Troubleshooting Publishing

"There are no new packages that should be published"

This means the version in package.json already exists on npm. You need to:

Bump the version in both packages
Commit the version change
Try publishing again

"ERR_PNPM_GIT_NOT_LATEST"

Your local git history differs from remote. Either:

Pull latest changes: git pull
Or use force push (be careful!): git push --force

"ERR_PNPM_GIT_UNCLEAN"

You have uncommitted changes. Either:

Commit your changes first
Or add --no-git-checks flag (not recommended)

Version Guidelines

Follow semantic versioning:

Patch (0.1.x): Bug fixes, small improvements
Minor (0.x.0): New features, non-breaking changes
Major (x.0.0): Breaking changes

Example version history:

0.1.0 - Initial release
0.1.1 - Bug fixes
0.1.2 - Add new feature (backwards compatible)
0.2.0 - Add breaking API changes
1.0.0 - Stable release

Troubleshooting

Metro WebSocket Connection Errors

If you see "WebSocket exception" or "Cannot connect to Metro":

Common cause: Port forwarding not set up (Android)

# Set up port forwarding
adb reverse tcp:8081 tcp:8081

# Verify Metro is running
curl http://localhost:8081/status
# Should return: {"packager":"running"}

If Metro crashed: Restart with cache clear

pnpm --filter example start -- --reset-cache

Build Issues

"Unable to resolve module" errors:

# Clean and rebuild
pnpm clean
pnpm install
pnpm build

# Clear Metro cache
cd packages/example
rm -rf .expo node_modules/.cache
pnpm start --clear

Babel transformation not working:

# Rebuild babel plugin
cd packages/babel-plugin-kstyled
pnpm build

# Clear example cache
cd ../example
rm -rf .expo
pnpm start --clear

Testing Your Changes

After making changes to kstyled or babel-plugin-kstyled:

Rebuild the package:
```
pnpm build
```
Clear example cache:
```
cd packages/example
rm -rf .expo
```
Restart Metro with clean cache:
```
pnpm start --clear
```
Reload the app: Press r in Metro terminal or reload in simulator

VSCode Debug Configurations

Useful launch configurations in .vscode/launch.json:

Fix Metro WebSocket Issues - Auto-fixes port forwarding and Metro connection
Start Metro (Reset Cache) - Starts Metro with clean cache
View Android Logs - Real-time Android logcat filtering

Questions?

If you have questions, please:

Check the README
Check the Documentation (includes Troubleshooting guide)
Open a Discussion
File an Issue

Thank you for contributing! 🎉

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History