Introduce a Debug mode

[adrienpoly]

This PR adds a debug mode to Stimulus and close #349

In debug mode application lifecycles, controller lifecycles and actions events are sent to the Stimulus Logger with a default output to the console. Each log includes context information available in a detailed view.

Example:

Usage

debug mode can be enabled during the Stimulus application initialization phase

import { Application } from 'stimulus'
import { definitionsFromContext } from 'stimulus/webpack-helpers'

const application = Application.start()
const context = require.context('./controllers', true, /\.js$/)
application.load(definitionsFromContext(context))

// enable Stimulus debug mode in development
application.debug = process.env.NODE_ENV === 'development'

Or even at run time as suggested here if application is accessible at the window level.

window.stimulusApplication = application

// and then in the console 
stimulusApplication.debug = true // or false to toggle the debug mode in production

Message content & styling

Content

Messages are collapsed groups. Title of the group follow the pattern emitter #action
The emitter can be application or a controller identifier

Examples:

• application #staring
• application #stared
• form #initialize
• form #connect
• form #submit -> action

Opening the group provides a context object with details:

• application (all)
• controller (controller lifecycle and actions)
• element (controller lifecycle and actions)
• identifier (controller lifecycle and actions)
• functionName (actions)
• currentTarget (actions)
• event (actions)
• target (actions)

Style

I applied a few colors with a variant for dark mode. I took Purple and Yellow from Basecamp website. Matter of taste and easily changeable.

light mode	dark mode

Values

Value changes are not logged at this point. It shouldn't be difficult to add if needed.

Namespacing

No particular namespace is applied to the log message at this point. This is a subject of discussion. Do we want something like :

Stimulus - emitter #action for the collapsed group title ?

Custom logger

By default, the logger is the console. A custom Loggercan be supply

application.logger = customLogger

Tests

This PR does not include tests at this point. I am not sure how you would like this to be tested. One approach I could think of is to create a custom Logger that would collect messages (could store them in the application). And then do some assertion on the amount of messages and type we receive. An approach a bit similar to the log_controller_test_case but at the application level this time.

[db0sch]

Thanks @adrienpoly for implementing this.
No more console.log in connect() 😉

Just a couple of small comments.

[ssaunier]

Thanks @adrienpoly for this work, can't wait to have a logger too! Typos in HTML resulting in not having the Stimulus Controller loaded happen, on dev habbit counter-measure has been console.log('👋') in the connect(), that change will improve the Developer Experience.

🤔 I wonder about the default though. From your description, it seems that we'd have to manually add that to our pack:

application.debug = process.env.NODE_ENV === 'development'

This opt-in approach is good for retro-compatibility, but in the meantime a lot of teams upgrading Stimulus would miss that feature. What would be the sensible default? I'm leaning towards having that line within the library, while still having the possibility to force no debugging in the application code with:

application.debug = false

[adrienpoly]

This opt-in approach is good for retro-compatibility, but in the meantime a lot of teams upgrading Stimulus would miss that feature. What would be the sensible default?

process.env.NODE_ENV === 'development'

@ssaunier I think the ENV variable work when you have a build system in place such as webpack but would not work if you are using the UMD version of Stimulus or the new autoloading approach from https://github.com/hotwired/stimulus-rails with Skypack.

So unless we would have a per build type default value for the debugger I think we need to default it to false.

[db0sch]

btw, that makes me think of something for v2 of this feature: wouldn't it be cool to log when a data-controller=... does not match any existing controller?
It should be a warning (not an error), as this might be intentional, and of course, only in development (and probably upon developer's opt-in, like this logger here).
Would save quite some times. Especially as I'm using namespaces in my controller's naming, and can be prone to typos and spelling mistakes (convention translation from lower snake case to kebab case... etc)

[weaverryan]

This looks incredible! Thank you @adrienpoly (I actually searched for this after seeing your debug mode over on stimulus-use (https://stimulus-use.github.io/stimulus-use/#/docs/debug).

I know from personal experience that this is rather annoying, but does anyone know if there's a plan/timeline to merge some PR's like this and create a 2.1 release? I'm working on a tutorial for Stimulus for the Symfony world and this feature, in particular, would be great to show off.

Also: is there anything we know blocking the PR? Missing tests?

Thanks!

[daya]

While we are waiting for the PR to be merged, not knowing what's preventing the merge, I tried the suggestion https://stimulus-use.github.io/stimulus-use/#/docs/debug and couldn't get the console.log or debugger to work. So presently I don't have a way to debug Stimulus controllers. Any help?

[adrienpoly]

@daya StimulusUse debug mode is only for some StimulusUse mixins (by example useDistpactch, useVisibility some others are still in progress). It does noyt cover all of the standard lifecycle events of Stimulus. This PR does

To the maintainers
I have seen that this PR #365 has been merged. It does add some test helpers for mocking the logger. This could be use to test this debug feature.

[dhh]

This is great @adrienpoly. I'd like to follow this up with a default assignment of the stimulus application instance to window, just like we do with Turbo now, such that it's easy to toggle on the debug mode.

[leastbad]

Please reconsider adding Stimulus to the global window namespace by default, as there's no reason to force this on people who don't need/want it.

Anyone that does want it can add

window.Stimulus = application

to their index.js.

[dhh]

This would make it easier to debug Stimulus both as a way to turn on/off logging, including in production, but also to inspect the state of registered controllers.

Do you have any cases where assigning stimulus to window would cause problems? Of course, even if we did move to doing this by default, one could also just add window.Stimulus = null to clear it out.

[leastbad]

I understand the functionality and the mechanics. I also think this PR is a nice enhancement. My comment is specifically in regards to adding global variables that aren't necessary.

I don't have anything to add beyond what I've said. My previous comment stands on its own merits.

A compromise might be to add the assignment to the standard index.js template, allowing folks to remove it easily while giving newcomers a globally accessible default.

[dhh]

Good point, @leastbad. I've updated both the Stimulus handbook and the default generated index.js in stimulus-rails to use the window.Stimulus assignment. Then it's easy enough for someone to change to use a local variable, if they don't think they benefit from the debugging benefits of the global 👍

[adrienpoly]

👍 for merging this PR

about the window assignment I will do more tests but potentially it could cause issues in app where multiple packs are loaded (each pack having Stimulus). With the assignment to const application it was handled transparently but as a global variable it probably requires having different names for each pack

[dhh]

Yeah, that's why we're better off just doing the default setup as generated code, and then people can change that if they have unique situations like that.