No instructions on debugging scripts

[StevePotter]

While authoring a script, I struggled to find a way to debug it. I looked in the docs and didn't find anything. I would be happy to submit a PR with instructions, unless repo authors prefer to do it.

What worked for me:

1. Start node-inspector
2. Install jscodeshift in my local repo as a dev dependency.
3. put debugger statement in my script
4. run jscodeshift via node with --debug-brk arg and added --run-in-band jscodeshift param. For example, I entered node --debug-brk ./node_modules/jscodeshift/bin/jscodeshift.sh -t my-refactor-script.js --run-in-band

If you add a file pattern at the end, it works fine, which in the case of debugging is helpful when you want to test just one trouble file.

Here is a screenshot of it working

I did not test debugging jscodeshift installed via npm -g.

For documentation, I'd like to see:

1. Brief node-inspector installation (which can be done locally or globally)
2. Example command to run in debug mode with and without a file pattern.

If you'd like me to put in the work, where should I put it? README, a wiki page, or somewhere else?

Thanks!
Steve

[alangpierce]

Agreed it would be nice to have better instructions, particularly around the use of --run-in-band.

I haven't tried it with jscodeshift specifically, but I think it's maybe more reliable to use the newer --inspect flag instead of node-inspector, as described here:
https://medium.com/@paul_irish/debugging-node-js-nightlies-with-chrome-devtools-7c4a1b95ae27

Another thing you can do is write the script in astexplorer (which is also really useful for getting immediate feedback and analyzing the AST) and drop into the debugger there. If you add a debugger; statement with the Chrome console open, you'll be able to debug your script. You can also just console.log any variables to inspect their prototypes and all that. Here's an astexplorer link with the right settings and a debugger; statement added:
https://astexplorer.net/#/gist/a3480c55d843b4f7afe2be6815818c8f/3bbf03fc658824e2a3e8f3ba5fe74b9e523b7193

[StevePotter]

Thanks for the reply @alangpierce. I had use astexplorer but never to run a codeshift mod on it. That's really awesome, basically an IDE for this. I would say that debugging scripts locally is useful. For example, in my script I use some lodash functions and you can't do imports in astexplorer.

All I would like is a little guidance as to where I should put the instructions and I'll get it done, using the --inspect flag instead of node-inspect (thanks for that by the way).

Have a good day!

[alangpierce]

👍 makes sense that it's still useful to run locally.

As far as I know, the only real documentation (other than scattered blog posts) is the README, so maybe best to just put it there. The project maintainers may have more thoughts on docs organization, especially if you send a PR with something specific. The project hasn't been very active recently, though, so unfortunately it might take a while for PRs to be considered.

[sjy]

Play much happier with vscode debugger tool;

// launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch via NPM",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "dev"],
            "port": 9229
        }
    ]
}

scripts: {
   "dev": "node --inspect ./node_modules/jscodeshift/bin/jscodeshift.sh -t react-tsx.js ./samples --dry -p --run-in-band --extensions tsx --parser babylon"
}

[aryeh-looker]

Would be great to have in the README 👍

[ElonVolo]

Added to docs. Thanks for lighting the fire on this!