Contributing to Ripple

August 25, 2026 ยท View on GitHub

Ripple is a TypeScript UI framework that combines the best parts of React, Solid, and Svelte into one cohesive package. Built as a love letter to frontend development, Ripple introduces a JS/TS-first approach with .tsrx modules that provide an excellent developer experience for both humans and LLMs.

This repository owns the Ripple runtime, Ripple compiler target, adapters, scaffolding, and framework integrations. Target-neutral TSRX language, compiler-core, formatting, linting, language-server, grammar, and editor work is maintained in tsrx-org/tsrx.

The Open Source Guides website offers valuable resources for individuals, communities, and companies looking to contribute to open source projects. Both newcomers and experienced contributors will find these guides particularly helpful:

Ways to Get Involved

There are numerous ways to contribute to Ripple, and many don't require writing code. Here are some ideas to get started:

  • Start experimenting with Ripple: Try out the Ripple Playground and see how it works. If you encounter issues or unexpected behavior, we'd love to hear about it through opening an issue.
  • Browse existing issues: Check out our open issues. You can help by providing workarounds or asking clarifying questions.
  • Submit fixes: Found an issue you'd like to tackle? Consider opening a pull request.
  • Help with documentation: As Ripple grows, we'll need comprehensive documentation. Any help improving clarity or filling gaps would be greatly appreciated.

We welcome all contributions! If you need guidance in planning your contribution, please reach out on our Discord server and let us know you're looking for some direction.

Issue Triage

A fantastic way to contribute without coding is helping triage issues and pull requests:

  • Request additional information when issues lack sufficient detail for resolution.
  • Identify stale issues that should be updated or closed.
  • Review code and suggest improvements.
  • Help organize and categorize incoming issues.

Development Process

Planning Major Changes

For significant new features or substantial changes, we encourage discussion before implementation. While we don't have a formal RFC process yet, please open an issue to discuss your ideas with the maintainers and community first.

Current Focus

Ripple is in early alpha, so our priorities are:

  1. Stabilizing core functionality
  2. Improving TypeScript integration (note that the internal codebase is still being migrated from JS, so some TypeScript errors are expected)
  3. Expanding test coverage
  4. Building and maintaining essential tooling

Keep in mind that this is a very early-stage project, so expect frequent changes and some rough edges.

Communication

Since Ripple is a new project with a small team, we'll do our best to respond to issues and PRs promptly. Join our Discord server for real-time discussion and updates.

Reporting Issues

We track bugs using GitHub issues. Before reporting a new issue, please check if someone has already reported the same problem.

For questions about using Ripple, our Discord server is the best place to get help and connect with other developers.

Creating Bug Reports

When opening a new issue, please include:

  • Clear description: Explain what you expected to happen and what actually occurred.
  • Reproduction steps: Provide step-by-step instructions to reproduce the issue.
  • Environment details: Include your operating system, Node.js version, and any relevant setup information.
  • Minimal example: If possible, create a minimal reproduction case that demonstrates the problem.

Important guidelines:

  • Report one bug per issue
  • Be as specific as possible
  • Include code samples when relevant

Pull Requests

Before You Start

For bug fixes, feel free to submit a pull request directly, but we recommend filing an issue first to discuss the problem and proposed solution.

For new features, please open an issue to discuss the implementation before starting work. This helps ensure your contribution aligns with the project's direction.

Keep pull requests focused and reasonably sized for easier review.

Development Setup

You'll need Node.js and pnpm installed.

  1. Fork the repository
  2. Clone your fork locally
  3. Run pnpm install to install dependencies
  4. Create a new branch from main for your changes

Development Workflow

Run the smallest checks that cover your change:

  • pnpm test --project ripple-client for client runtime work
  • pnpm test --project ripple-server for SSR work
  • pnpm test --project ripple-hydration for hydration work
  • pnpm test --project tsrx-ripple for Ripple compiler-target work
  • pnpm typecheck for source changes
  • pnpm format:check before submitting

Testing

While our test suite is still being developed, please:

  • Test your changes manually
  • Verify that existing functionality still works
  • Include test cases for new features when possible
  • Document your testing approach in the PR description

Code Style

  • Follow existing code patterns in the repository
  • Use meaningful variable and function names
  • Include appropriate comments for complex logic
  • Maintain TypeScript types where applicable

Submitting Your PR

Before submitting:

  1. Test thoroughly: Ensure your changes work as expected
  2. Write clear commit messages: Describe what and why, not just what
  3. Update documentation: If you've changed APIs or added features
  4. Add a changeset: For user-facing changes (see below)
  5. Target the main branch: All PRs should be opened against main
  6. Keep it focused: One feature or fix per PR

Changesets

We use Changesets to manage versioning and changelogs. If your PR includes user-facing changes (bug fixes, new features, breaking changes), you should add a changeset:

pnpm changeset

This will prompt you to:

  1. Select the packages affected by your change
  2. Choose a patch bump (the only bump type currently allowed)
  3. Write a summary of your changes (this becomes the changelog entry)

The command creates a markdown file in .changeset/ that should be committed with your PR. When your PR is merged, the release workflow will automatically:

  1. Aggregate all changesets into a "Version Packages" PR
  2. When that PR is merged, publish to npm

When to add a changeset:

  • User-facing changes use patch while the project remains prerelease.
  • Do not select minor or major; CI rejects those bump types.

When NOT to add a changeset:

  • Documentation-only changes
  • Internal refactoring with no user-facing impact
  • Test-only changes
  • CI/tooling changes

Include in your PR description:

  • Summary of changes
  • Testing performed
  • Any breaking changes
  • Related issue numbers

Development Guidelines

Code Conventions

Since Ripple is TypeScript-first:

  • Prioritize type safety
  • Use descriptive names for variables and functions
  • Follow existing patterns in the codebase
  • Comment complex logic clearly

Commit Messages

Write clear, descriptive commit messages that explain both what changed and why.

License

By contributing to Ripple, you agree that your contributions will be licensed under the same license as the project. MIT License

Getting Help

  • Discord: Join our community server for real-time discussion
  • GitHub Issues: For bugs and feature requests
  • GitHub Discussions: For general questions and ideas (when available)

We're excited to have you contribute to Ripple's development! Even though the project is young, every contribution helps shape its future.