Open chasenlehara opened 7 years ago
@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.
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.
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.
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:
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?
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.
Yarn has a similar offering for create-*
:
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 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
.
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.
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:
npx
.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
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?
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.
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?
@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.
I would take it one step further than what @matthewp proposed.
I would actually make the default installation NOT include testee
, or ssr
. Specifically I am saying that --light
option shouldn't be required because it is the default.
Don't get wrong I 100% agree that SSR, and testing are important to an application, but they are furthest thing from my mind when I am developing a brand new application.
I care about one thing when starting a new application, and that is getting into writing my specific application code as soon as possible. This includes not being distracted by a whole bunch of other concepts (or code or files) that I am just not ready to deal with at the start of a new application.
@mjstahl We could make a can-steal
generator and just show that from CanJS.com. Imo, DoneJS is about SSR / Testing / etc.
One of the things that first confused me when building a DoneJS app was that the special commands, like
donejs develop
anddonejs 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 ofnpm run develop
?