Project

stimulus-viz

0.0
No release in over 3 years
stimulus-vizminokiti11/stimulus-vizHomepageDocumentationSource CodeBug TrackerWiki
Static analysis tool for Stimulus controllers and DOM bindings in Rails applications
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
427
Stars
1
Forks
0
Watchers
0
 Releases
Current version
0.1.1
Total releases
2
First release
1980-01-02
Latest release
1980-01-02
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-01-01
Reverse Dependencies
0

 Dependencies

Development

minitest
~> 5.0
rake
~> 13.0

Runtime

json
~> 2.0
thor
~> 1.0
 Project Readme

StimulusViz

Gem Version

Rails/Hotwire Stimulus visualization tool for static analysis of Stimulus controllers and DOM bindings.

Installation

Add this line to your application's Gemfile:

gem 'stimulus-viz'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install stimulus-viz

Setup

If you're using the development version with git submodules:

git submodule update --init --recursive

Usage

Scan Rails Project

Scan your Rails project for Stimulus controllers and DOM bindings:

stimulus-viz scan --root /path/to/rails/project --out .stimulus-viz.json

List Controllers

List all discovered controllers:

stimulus-viz list --cache .stimulus-viz.json

Show Bindings

Show DOM bindings, optionally filtered by controller:

stimulus-viz bindings --cache .stimulus-viz.json
stimulus-viz bindings --cache .stimulus-viz.json --controller presence

Lint Analysis

Run lint checks on your Stimulus usage:

stimulus-viz lint --cache .stimulus-viz.json
stimulus-viz lint --cache .stimulus-viz.json --fail-on warn

Lint levels:

  • info: Empty bindings (controller without actions/targets/values)
  • warn: Unknown controllers, suspicious action formats
  • error: Critical issues

Export Data

Export scan results in different formats:

# Export as pretty JSON
stimulus-viz export --cache .stimulus-viz.json --format json --out output.json

# Export as DOT graph
stimulus-viz export --cache .stimulus-viz.json --format dot --out graph.dot

Output Schema

The tool generates JSON with the following structure:

{
  "meta": {
    "root": "/path/to/project",
    "generated_at": "2024-01-01T12:00:00Z"
  },
  "controllers": [
    {
      "name": "presence",
      "module": "app/javascript/controllers/presence_controller.js",
      "elements": 3,
      "actions": ["highlight", "connect"],
      "targets": ["list", "item"],
      "values": ["fadeMs", "url"]
    }
  ],
  "bindings": [
    {
      "id": "el_0001",
      "selector": "app/views/home/index.html.erb:42 <div#presence>",
      "controllers": ["presence"],
      "actions": ["turbo:before-stream-render->presence#highlight"],
      "targets": [
        {
          "controller": "presence",
          "name": "list",
          "selector": "(static)"
        }
      ],
      "values": [
        {
          "controller": "presence", 
          "name": "fadeMs",
          "value": "250"
        }
      ],
      "broken": false
    }
  ],
  "lint": [
    {
      "level": "warn",
      "title": "Unknown controller",
      "detail": "Controller 'missing' is referenced but not found",
      "hint": "Check controller name spelling",
      "where": "app/views/test/index.html.erb:10"
    }
  ]
}

Development

After checking out the repo, run:

git submodule update --init --recursive
bundle install

To run tests:

bundle exec rake test

To install this gem onto your local machine:

bundle exec rake install

Testing

The test suite uses the yasslab/sample_apps repository as fixtures via git submodules. Tests create temporary directories with minimal Stimulus setups to verify scanning functionality.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the terms of the MIT License.