Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (141 loc) · 4.71 KB

CONTRIBUTING.md

File metadata and controls

197 lines (141 loc) · 4.71 KB

Contributing to Flashonic

Thank you for your interest in contributing to Flashonic! This document provides guidelines and information for contributors.

🚀 Getting Started

Prerequisites

  • Bun >= 1.0.0
  • Rust >= 1.70.0
  • Node.js >= 18.0.0 (for compatibility testing)

Development Setup

  1. Clone the repository

    git clone https://github.com/flashonic/flashonic.git
cd flashonic

  2. Install dependencies

    bun install
bun run install:all

  3. Build the project

    bun run build

  4. Run tests

    bun test

  5. Start development

    cd examples/react-app
bun run dev

📁 Project Structure

flashonic/
├── packages/
│   ├── cli/        # Command-line interface
│   ├── server/     # Development server
│   ├── transform/  # Rust transformation engine
│   ├── cache/      # Persistent caching
│   └── plugin/     # Plugin system
├── examples/
│   └── react-app/  # Example React application
├── scripts/        # Build and utility scripts
└── docs/          # Documentation

🛠️ Development Guidelines

Code Style

  • TypeScript: Use strict TypeScript with proper typing
  • Rust: Follow standard Rust conventions with cargo fmt
  • Formatting: Use Prettier for TypeScript/JavaScript files
  • Linting: Use ESLint for code quality

Commit Messages

Follow the Conventional Commits specification:

type(scope): description

feat(server): add WebSocket HMR support
fix(transform): resolve SWC parsing error
docs(readme): update installation instructions

Testing

  • Write unit tests for new features
  • Ensure all tests pass before submitting PR
  • Add integration tests for complex features
  • Test performance improvements with benchmarks

🎯 Performance Goals

When contributing, keep these performance targets in mind:

  • Cold start: <200ms on small projects
  • HMR latency: <10ms for typical module edits
  • Production build: <5s for medium React app
  • Cache hit rate: >95% on restart

🔧 Working on Specific Areas

Server Development

The development server is built with Bun and handles:

  • HTTP serving with ESM module resolution
  • WebSocket-based HMR
  • File watching and change detection
  • Plugin integration

Key files:

  • packages/server/src/index.ts - Main server implementation
  • packages/server/src/hmr.ts - HMR logic

Transform Engine

The transform engine uses Rust with SWC and LightningCSS:

  • JavaScript/TypeScript compilation
  • CSS processing and optimization
  • AST-based transformations

Key files:

  • packages/transform/src/lib.rs - Rust transform implementation
  • packages/transform/index.ts - TypeScript bindings

Caching System

The caching system provides persistent storage:

  • Content-based cache keys
  • RocksDB for persistence
  • Memory-first with disk fallback

Key files:

  • packages/cache/src/index.ts - Cache manager implementation

Plugin System

The plugin system allows extensibility:

  • Rollup-compatible API
  • WASM plugin support
  • Hot-swappable plugins

Key files:

  • packages/plugin/src/index.ts - Plugin manager and API

🐛 Bug Reports

When reporting bugs, please include:

  1. Environment information

    • Operating system and version
    • Bun version
    • Node.js version (if applicable)
    • Rust version (if building from source)

  2. Reproduction steps

    • Minimal code example
    • Configuration files
    • Command that triggers the bug

  3. Expected vs actual behavior

    • What you expected to happen
    • What actually happened
    • Error messages or logs

💡 Feature Requests

For new features, please:

  1. Check existing issues to avoid duplicates
  2. Describe the use case and motivation
  3. Provide examples of how the feature would be used
  4. Consider performance impact on our goals

📝 Documentation

Help improve our documentation:

  • Fix typos and unclear explanations
  • Add examples and use cases
  • Improve API documentation
  • Translate documentation to other languages

🎉 Recognition

Contributors will be recognized in:

  • README.md contributors section
  • Release notes for significant contributions
  • Special thanks in documentation

📞 Getting Help

  • Discord: Join our Discord server
  • GitHub Discussions: Use GitHub Discussions for questions
  • Issues: Create an issue for bugs and feature requests

📄 License

By contributing to Flashonic, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Flashonic! 🚀