Contributing to PhoenixExRatatui

Copy Markdown View Source

Thanks for the interest in contributing!

PhoenixExRatatui is built on ExRatatui. Consider contributing to the upstream library too when a feature is missing or something is not working. Contributions are welcome everywhere!

This guide covers the setup.

Setup

  1. Clone the repo:
git clone https://github.com/mcass19/phoenix_ex_ratatui.git
cd phoenix_ex_ratatui
  1. Prerequisites:
  • Elixir 1.17+ and Erlang/OTP 26+.
  • Node.js 22+ — only needed to rebuild the JS hook bundle. End users installing from hex don't need it.
  1. Fetch dependencies:
mix deps.get
mix assets.install   # cd assets && npm install

Running Tests

mix test
mix test --cover        # must report 100.00% Total

The suite uses Phoenix.LiveViewTest to drive the live widget end-to-end without a browser. It also includes property-based invariants via stream_data — proving the Renderer.Html cell/diff encoding round-trips losslessly through JSON across the full input space. Properties run as part of the regular mix test invocation.

Bundling the JS

mix assets.build       # cd assets && npm run build (minified)
# or
cd assets && npm run build:dev   # with sourcemaps

The bundled output lands at lib/assets/phoenix_ex_ratatui/main.js. The file is committed so the published hex package needs no Node toolchain at install time.

When anything under assets/js/ changes, rerun mix assets.build and commit the regenerated bundle.

The hook's pure logic (color/style/key decoding) has unit tests under assets/test/. Run them with cd assets && npm test — Node's built-in test runner, no extra deps. CI runs them on every push.

Branching and Commits

  • Branch from main
  • Keep commits focused and atomic
  • Use descriptive commit message prefixes: feat:, fix:, docs:, test:, refactor:, chore:

Pull Requests

Before submitting a PR, make sure the following pass:

mix format --check-formatted
mix compile --warnings-as-errors
mix credo --strict
mix dialyzer
mix test --cover
  • Keep PRs focused — one feature or fix per PR
  • Add tests for new functionality
  • Add @doc, @spec, and @moduledoc for new public functions and modules
  • Update documentation (moduledocs, CHANGELOG, README if applicable)
  • For breaking changes, include migration notes in the CHANGELOG
  • Follow existing code style and patterns
  • Ensure CI passes before requesting review