Contributing to reflow

July 12, 2026 · View on GitHub

Thanks for your interest in contributing! 🎉

We welcome bug fixes, new features, documentation improvements, and ecosystem integrations. This guide covers the expected workflow for contributing to reflow.

Quick Start

# Clone the repo
git clone https://github.com/valtors/reflow.git
cd reflow

# Install dependencies
npm install

# Run the full verification suite
npm run verify

Development

Scripts

Command	Description
`npm run build`	Build all entry points (ESM + CJS + DTS)
`npm test`	Run tests with Vitest
`npm run typecheck`	TypeScript type checking
`npm run lint`	Lint with Biome
`npm run verify`	Full CI check (typecheck + lint + test + build)
`npm run lint:fix`	Auto-fix Biome lint issues where possible
`npm run test:watch`	Run Vitest in watch mode

Project Structure

src/
├── core/        # Framework-agnostic core (breakpoints, media, viewport, etc.)
├── react/       # React hooks & components
├── vue/         # Vue 3 composables
├── svelte/      # Svelte stores
├── styles/      # Fluid typography & CSS clamp utilities
├── server/      # SSR helpers (Next.js, Express)
├── testing/     # Test utilities & viewport mocking
└── tailwind/    # Tailwind CSS preset generation

Tests live in test/.

Architecture

All framework adapters (react/, vue/, svelte/) wrap the same core/ modules. When adding a feature:

Implement the core logic in src/core/
Add framework bindings in each adapter
Write tests in test/

Code Style

We use Biome for linting and formatting
Run npx biome check --write src test to auto-fix
No ESLint or Prettier — Biome handles both
Keep framework-specific code out of src/core/
Maintain SSR-safe behavior for public APIs

Testing

Framework: Vitest with happy-dom
Tests live in test/
Run npm test or npx vitest --watch
Add or update tests for any functional change

Submitting Changes

Fork the repo and create a feature branch
Make your changes
Run npm run verify to ensure everything passes
If your change affects users, add a changeset with npx changeset
Open a PR with a clear description

Commit Convention

We follow Conventional Commits:

feat: — New feature
fix: — Bug fix
docs: — Documentation
test: — Tests
chore: — Maintenance

PR Guidelines

Keep PRs focused — one feature or fix per PR
Include tests for new features
Update JSDoc for public API changes
Ensure npm run verify passes
Link related issues or discussions when relevant

Reporting Issues

Use GitHub Issues
Include reproduction steps and environment details
Check existing issues before opening a new one

Community

GitHub Discussions — Questions, ideas, show & tell
Roadmap — See what's planned
Code of Conduct — Expected community standards

License

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

For AI Agents

If you're an AI agent contributing to reflow, here's what you need to know:

Run npm run verify before committing. This runs typecheck, lint, test, and build. It must pass.
Use the existing hooks as templates. Copy the pattern from src/react/useBreakpoint.ts or src/solid/useBreakpoint.ts.
Every hook must be SSR-safe. No window or document access without a guard.
Export new hooks from the framework's index.ts.
Add tests in test/ following the existing naming pattern.
No comments in code unless logic is non-obvious.
Keep zero runtime dependencies in core. Framework adapters may use framework-specific APIs.
Commit messages: lowercase, short, no conventional commits prefix needed.

File Structure

src/
  core/           # Framework-agnostic (breakpoints, media, viewport, store)
  react/          # React hooks + components
  vue/            # Vue composables + plugin
  svelte/         # Svelte stores
  solid/          # Solid hooks
  qwik/           # Qwik adapters
  preact/         # Preact (reuses react/)
  angular/        # Angular wrappers
  lit/            # Lit adapters
  styles/         # CSS utilities (fluidClamp, viewport units)
  testing/        # Test utilities
  server/         # SSR helpers
  tailwind/       # Tailwind preset

Adding a Hook

Create src/<framework>/useNewHook.ts
Follow the pattern from an existing hook in the same framework
Export from src/<framework>/index.ts
Add a test in test/
Run npm run verify
Open a PR