Contribute to RUNILIB
RUNILIB is built by the community, for the community. Whether you fix a typo, improve docs, or ship a new feature - every contribution counts.
What you get from it
Real-world impact
Your code runs in production apps used by real developers every day.
Open source cred
Build a visible portfolio with meaningful contributions to a real ecosystem.
TypeScript mastery
Dive deep into advanced TS patterns, generics, and cross-platform architecture.
Code reviews
Get detailed, constructive feedback from experienced engineers.
Community
Join a network of developers passionate about cross-platform DX.
Recognition
All contributors are credited in releases, README, and the website.
Step-by-step guide
Pick an issue
Browse open issues on the mirror repos (runilib/react-formbridge, runilib/react-walkit). Look for good first issue for an easy start, or help wanted for something more involved. Issues are automatically mirrored to the runilib monorepo where the work happens. If you have a new idea, open an issue first to discuss it before coding.
Fork & clone
Fork the runilib/runilib monorepo on GitHub, then clone your fork locally. Pull requests are opened against the monorepo - the mirror repos are read-only for code. The project uses Yarn 4 workspaces with Corepack.
| # Always branch from main |
| git checkout main |
| git pull origin main |
| # Use descriptive branch names |
| git checkout -b feat/formbridge-valibot-bridge |
| git checkout -b fix/walkit-ios-scroll-crash |
| git checkout -b docs/contributing-guide |
| git checkout -b chore/update-styled-components-v6 |
Set up the environment
Install dependencies, then run the dev server. Each package has its own dev script. The root turbo dev command starts everything in parallel.
| # 1. Enable Corepack to use the pinned Yarn 4 version |
| corepack enable |
| # 2. Fork runilib/runilib on GitHub, then clone your fork |
| git clone https://github.com/YOUR_USERNAME/runilib.git |
| cd runilib |
| # 3. Install all workspace dependencies |
| yarn install |
| # 4. Start everything in dev mode (Turborepo) |
| yarn dev |
| # Or target a specific workspace |
| yarn workspace @runilib/react-formbridge dev |
| yarn workspace @runilib/react-walkit dev |
Make your changes
Work on your feature or fix. Follow the code style guide below. Write or update tests as needed. Make sure nothing is broken by running the test suite.
Run quality checks
Before pushing, run typecheck, lint, and tests. All three must pass. The CI will also run these checks automatically on your PR.
| # Type check the entire monorepo |
| yarn typecheck |
| # Run all tests (web + native) |
| yarn test |
| # Lint |
| yarn lint # or: yarn lint:fix |
| # Run everything at once before pushing |
| yarn typecheck && yarn lint:fix && yarn test |
Open a Pull Request
Push to your fork and open a PR against the main branch. Use the PR template - fill in what changed, why, and how to test it. Link the issue you're resolving.
Code review
A maintainer will review your PR and leave comments. Address the feedback, push new commits - do not force-push during review. The conversation is part of the process.
Merge & celebrate 🎉
Once approved, your PR gets merged. You'll be credited in the changelog and your GitHub username appears on the contributors list. Welcome to the team!
Standards we follow
TypeScript strict mode
All code must compile with strict: true. No any, no @ts-ignore without a comment explaining why.
No CSS files
Styling exclusively via styled-components. No inline style objects except for truly dynamic values (positions, percentages from state).
Transient props
Use $prefixed props for styled-components to avoid forwarding to the DOM - e.g. $active, $color, $open.
Named exports
Always use named exports. No default exports except for pages and the App root.
Cross-platform first
Every field, component, and hook must work on React AND React Native. Test both. Platform-specific code goes in /web or /native sub-folders.
Tests required
New features need tests. Bug fixes need a regression test. Run yarn test before pushing.
Conventional commits
Follow Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:. This powers the changelog generator.
No side effects on import
Library entry points must be pure. setLocale() and other configurators are explicit calls - never run automatically on import.
Commit message format
| # ✅ Good commit messages |
| feat(formbridge): add field.phone() with country selector |
| fix(walkit): prevent tour from crashing on unmounted steps |
| docs(tooltip): add spotlight mode example to README |
| refactor(formbridge): extract validation engine to separate module |
| test(walkit): add multi-screen tour persistence tests |
| chore: update dependencies to latest patch versions |
| # ❌ Bad commit messages |
| git commit -m "fix" |
| git commit -m "WIP" |
| git commit -m "changes" |
| git commit -m "Update stuff" |
PR checklist
Run through this list before opening your PR. Every item should be checked.
Start here
These issues are well-scoped, documented, and a great way to get familiar with the codebase.
Stay connected
Ask questions, share ideas, and meet other contributors.
Contributors wall
Every merged contribution earns a spot here. Code, docs, design, translations, bug reports - all count.
Contributor avatars are pulled from the GitHub API. See the full list on GitHub →
Ready to make your first contribution?
The best way to start is to just pick an issue and dive in. The maintainers are here to help.