Proposal: use npm run instead of the donejs command

[chasenlehara]

One of the things that first confused me when building a DoneJS app was that the special commands, like donejs develop and donejs build, are just running npm scripts[1]. When I didn’t know about npm scripts, the donejs commands seemed like “magic” (something specific to using the donejs cli), and when I did learn about npm scripts, then it seemed unnecessary to have to install the DoneJS cli to work in a project that was generated with DoneJS.

Is there a reason why we specifically encourage commands like donejs develop instead of npm run develop?

[justinbmeyer]

@chasenlehara We do it for uniformity. donejs add app can not be run through npm run. Things like npm run add component foo/bar bar is a mouthful compared to donejs add component foo/bar. This would also mean having an add script, which might be desired for other contexts.

[chasenlehara]

Sorry, I wasn’t clear in my original post; I’m not advocating for something like npm run add component, rather that all of the commands that are just running npm scripts be documented with npm run.

For me, it makes sense to differentiate between the commands that are special to our CLI vs. npm. For example, we show installing Bootstrap with npm install bootstrap; I think it’d be silly if we showed donejs install bootstrap in our docs. In the same vein, we show donejs test in the in-depth guide, when I think we should be showing npm test because the DoneJS CLI isn’t doing anything special in this situation.

[andrejewski]

I agree with @chasenlehara. When I first encountered donejs test I thought "okay, a test command that is tied to donejs .. this is gonna suck because now I'll have to change all my CI test commands because it doesn't follow the npm test convention." NPM tasks and Donejs tasks to do not overlap enough for uniformity to be a strong enough argument, in fact that uniformity is a source of confusion. For me, because I see something that is not npm run and assume there must be some magic going on. Most target users know how to use npm scripts already.

[matthewp]

Bumping this now that npx is a thing and I think you can run generators through npm?

npx provides many of the same features that the donejs cli is used for. I'm not as familiar as some other people so I'd like to get their feedback. @BigAB @justinbmeyer have discussed the idea. Some of the commands we have:

• donejs add x (generator)
• donejs serve (running scripts)
• donejs upgrade

I think that's it... can we provide all of this through npx _ types of commands?

Also, what does this mean for yarn projects, or do we just only support npm?

[BigAB]

I don't know enough about yarn but, regarding npx:

npx, included by default with npm/node now, reduces the need for global installs like our done-cli.
When you use npx to create the project, like npx donejs add app, npx would pull down the donejs package temporarily run the add app command on it then delete it (effectively).

In the project though, if donejs is a dependancy that puts commands in the node_modules/.bin directory (which it does), when you are in the project you can do npx donejs add component, effectively sugar for ./node_modules/.bin/donejs add component.

There is also a new thing in npm init where you can do something like npm init donejs-app and it will look for a package in the registry called create-donejs-app and use npx to download it and execute the main binary.

You can also use the scopes so you could do something like npm init @donejs which would look for end execute the package called @donejs/create

With npx and npm offering these kinds of utilities, it's probably worth considering not only implementing these features, but maybe modifying our own donejs-cli api to be more friendly when using them.

[BigAB]

Yarn has a similar offering for create-*:

https://yarnpkg.com/en/docs/cli/create

[matthewp]

Proposal

tldr; Transition away from donejs-cli in favor of npm init / npm run commands.

This proposal seeks to deprecate the donejs cli and instead use the built-in features of npm (and possibly) yarn to generate and control donejs applications.

This was discussed on a recent live stream (37:24).

The Problem

The global donejs command was added before releasing donejs 0.4 in order to provide a way to create new donejs applications with all of the necessary dependencies installed, as well as a way to generate new components, models, and other modules within a donejs application. We had original seeked to have developers only need to do npm install donejs locally within their project, but this didn't give us everything we needed.

We designed the donejs cli so that it is only a thin layer around a project's package.json scripts and binaries installed within node_modules/.bin.

Since the beginning we have had a problem with donejs apps taking a long time to install. We have improved this over time by deferring installing things until we need them, through generators such as donejs add firebase.

Factors

Since donejs was first released, npm and yarn have created ways to generate new projects without needing a special global cli. Additionally npx provides a way to install and run binaries. This provides a way to avoid maintaining the donejs cli any longer.

The Solution

This proposal seeks to do away with the donejs cli, and instead rely on npm/npx. This means that a basic donejs app could be installed with:

> npm init donejs-app my-app

This will run create-donejs-app which will generate a new donejs app.

The initial package.json will look something like this:

{
  "name": "my-app",
  "main": "index.js",
  "version": "1.0.0",
  "scripts": {
    "start": "http-server -p 8080"
  },
  "dependencies": {
    "can": "^5.6.0",
    "steal": "^2.0.0",
    "http-server": "^1.0.0"
  }
}

Notice that we only install can and steal. done-ssr, testee, etc are not included.

It's likely we'll want a couple of more things, such as perhaps steal-qunit or another testing utilities. The point is that by default we only include what is minimally needed to get started.

When you want server-side rendering you can install done-serve using npx donejs-add like so:

> npx donejs-add ssr

This will install the donejs-ssr generator which will add all of the necessary scripts to your package.json which will then let you run:

> npm run develop

When you want testing perhaps you run something like:

> npx donejs-add testing

When will install testee and another other needed utilities.

To generate a new component you can run:

> npx donejs-add component my-component

Here donejs-add is a project that works the same way as our current donejs add component... utility.

The goals here are:

1. Bootstrapping a new project should be very quick.
2. It should be an easy way to get started working on a canjs app.
3. You only install what you need, when you need it, by using npx.

[BigAB]

I like the above but I would suggest:

The initial package.json will include a dev dependency of donejs (or something like that), the donejs dependency includes the add (or donejs-add) executable in the node_modules/.bin dir.
(*and of course any other commands donejs provides)

So that way when you npx add component at the root of the project, npx doesn't fetch it, temp install it, run it and delete it, rather it detects and uses the add executable instead

[matthewp]

Thanks @BigAB, the specifics are definitely something we can discuss, I just wanted to get the proposal ready for the survey. We could have donejs-add be a dependency of the generated app perhaps. I was thinking this wouldn't be necessary because npx would install it when you use it. Does npx also delete the binary after it runs, it's not added to your package.json as a dependency?

[matthewp]

Ok, npx works a little differently than I thought. It does not install the package locally, but does so in some global cache that it keeps. This means that donejs-add likely does need to be installed with the project. I'll update the proposal to be more npm run based.

[justinbmeyer]

I'm a bit uneasy about the lack of testing and ssr. A related concern is that we should probably setup people with pushstate, we'll need more that http-server for this.

What versions of node is this all supported?

[matthewp]

@justinbmeyer You might have missed it, but the proposal mentions that likely something like steal-qunit would also be included from the start. This means the generated app would include a test page and default tests like it has today.

Testee likely would not be included (it's one of the things that takes a long time to install), but there's less of a reason for Testee until you have CI.

Installing testee and ssr takes away from the idea of a having a lightweight way to use steal and canjs together. Another option I thought of is having a "light" mode or something that works like the above.

So basically:

> npm init donejs-app my-new-app

Would include basically everything that gets installed today. But if you did:

> npm init donejs-app my-new-app --light

Would be the slimmed down version like shown above. I prefer the install-as-you-go approach because I think having 2 modes will be harder to maintain.