Support a description for npm scripts

[tgvashworth]

Hey — this project is great, exactly what I've been looking for. Thanks for building it!

My team has a lot of scripts to manage, and some have similar names but different behaviour (eg, build and build_watch). I'd like to be able to provide a description of the commands as documentation. Is that something you'd be willing to see added? (I'll happily do the PR)

I was thinking it could use the config key in package.json:

{
  "scripts": {
    "start": "...",
    "test": "...",
    "lint": "..."
  },
  "config": {
    "ntl": {
      "start": "Start a development server",
      "test": "Run the unit tests",
      "lint": "Lint JavaScript and Sass"
    }
  }
}

Any thoughts?

[ruyadorno]

hi @PhUU really glad you like it 😄 thanks!

we had one similar contribution adding additional context to the listed tasks but it only shows the content of the npm scripts, you can see it here: #2

Yours is a great idea and some people might find it useful, I would definitely merge it 👍 the only requirements would be to squash commits, provide tests and update the README to explain how to use it 😊

[tgvashworth]

@ruyadorno cool!

How do you like the idea of putting inside config.ntl? Are you likely to to use it for anything else? If so we could use a different path.

[ruyadorno]

👍 looks awesome, please go ahead

I don't plan to use it for anything else but I'm inclined to be very receptive towards accepting new ideas for this project, so we never know 😊

[tgvashworth]

Ok — at risk of being verbose, I'll do config.ntl.docs and see how that feels to use.

[ruyadorno]

oh, someone just did this: https://github.com/srph/npm-scripts-info

I think it's worth using something like this instead of creating/maintaining our own specs for the descriptions

[ndelangen]

Concerning integrating this into npm itself and add a description to a npm script:
npm/npm#15154 (comment)

[zeke]

I like the bash comments idea outlined in npm/npm#15154 (comment)

[ruyadorno]

@zeke 👍 agreed, the bash comments looks like something that can fit well inside the scope of ntl without too much overhead

[mischah]

Hej @ruyadorno,

I’d love to see that feature 💖

But I must say that I would prefer to configure descriptions via a ntl field in package.json similar to the first proposal from @tgvashworth:

{
  "scripts": {
    "start": "…",
    "test": "…",
    "lint": "…"
  },
  "ntl": {
    "start": "Start a development server",
    "test": "Run the unit tests",
    "lint": "Lint JavaScript and Sass"
  }
}

Only difference: Get rid of the wrapping config property.
Reason: This is like other tools handle it (e.g. Jest, ESLint etc.)

Reason for introducing an own field instead of using bash comments:

• Readability: Imagine these, or these would have additional comments 😳
• Maintainability: I guess having just another object would make it easier to add another useful feature: Showing only scripts which do have a description.

[mischah]

or to be more future-proof:

"ntl": {
    "descriptions": {
      "start": "Start a development server",
      "test": "Run the unit tests",
      "lint": "Lint JavaScript and Sass"
    }
  }

This way you wouldn’t need to do a major bump in case you will store other configs into the ntl field.

[ruyadorno]

hi @mischah I'm totally down to support both methods! 👍

specially after the v2.0.0 refactor, there's so little code left in ntl itself that it can totally handle some minor bloat like that.

And then everyone can be happy! 🎉

[ruyadorno]

I'll give it a few weeks to see if anyone wants to send in a PR to support any of these description methods since I'm very burned out from all the effort that went into getting ipt and ntl to the nice state they are now.

but fear not my friends, if nobody feels like doing it I'll implement at least one of those to start with but tbh I def want to see both description methods in!

[ndelangen]

@ruyadorno I'm sad to hear you're burned out because of the OS work. Just wanted to post, that you have no obligation to do this whatsoever, you should do things you like doing in your free time.

Truly appreciate the hard work you've put into this 🙇‍♂️

[ruyadorno]

thank you for the kind words @ndelangen ❤️

Please don't worry about it! I didn't meant burnout in the sense of the mental disorder, I should pb have used the word exhausted instead 😳it was just a bad choice of words from my part as english is my third language - I apologize to anyone reading this suffering from the real thing, it was def not my intention to diminish the issue.

All that said, it was also lots of fun working on it, the exhaustion is just due to the big final sprint to get everything ready for release 😊

I'm really happy to see there's more people out there enjoying and using the project 😄at the end of the day it's what keep me motivated! All the best and thanks again!

[mischah]

I’m about to start to work on this 😘