Docs should not encourage global npm installation

[dpogue]

Currently the docs say to run sudo npm install -g cordova which is not great from a best practices standpoint. We should never encourage running npm with sudo because of permissions problems, and npm recommends not installing anything globally if it can be helped.

We should update our documentation to use npx cordova instead (npx requires npm >=5.2.0), and add cordova as a devDependency to our hello-world project template.

[brody4hire]

Currently the docs say to run sudo npm install -g cordova which is not great

+1 (+100 if you change "not great" to "bad")

use npx cordova instead

• ~~does not work for create~~ I stand corrected by @dpogue on this point. However npx cordova create MyProject introduces a small delay to install cordova in some temp location, not so graceful IMHO.
• I could image a developer wanting to use own installation of Cordova CLI, regardless of what is used by the project

I ~~would favor an~~ can think of a possible approach inspired by React Native:

• Simplistic create Cordova app tool
• The generated Cordova app could have npm scripts for some the most important tasks from Cordova CLI

I guess the user could have a choice whether to use "npx cordova" or own installation of Cordova CLI for other tasks.

P.S. I would now favor the suggestion by @raphinesse below.

[dpogue]

It works perfectly for create: npx cordova create MyProject You can even use a specific version: npx [email protected] create MyProject

[raphinesse]

I'd suggest presenting both alternatives:

• global installation (without using sudo)
• Add to devDeps and use with npx (advertise as preferred!)

And then just keep using plain cordova throughout the docs.

[janpio]

There probably was a reason why sudo is mentioned currently?

And then just keep using plain cordova throughout the docs.

Will this work on all platforms without the global cordova install?

[dpogue]

And then just keep using plain cordova throughout the docs.

Will this work on all platforms without the global cordova install?

No, if you don't install cordova globally, you'd always need to prefix it with npx when you want to run it.

npx will look inside node_modules for it, and use it from there if it exists, or else it will install it into a temporary folder and run it from there for the duration of the command

[raphinesse]

There probably was a reason why sudo is mentioned currently?

@janpio I suppose because for most default setups you need root access to install npm packages globally. This is widely considered a bad idea though. Instead you should setup npm to install global packages to your home folder, for example. Other than that, sudo is still mainly an Ubuntu thing, or am I mistaken?

Anyway, I was suggesting the following:

Inform the user once about his options on how to install cordova:

• global installation (maybe with a remark/link or two about running npm as root)
• project-local installation (remark about it being preferred & reasons for that; remark that whenever the docs say run cordova you have to run npx cordova to use the local version)

Afterwards don't worry to mention npx anywhere and everywhere but only refer to cordova.

I hope I have made myself clearer now.

[janpio]

remark that whenever the docs say run cordova you have to run npx cordova to use the local version

That's what won't work for 95% of users, so it will effectively be no substantial change to the current state (which is fine of course, but you should be aware of it).

Re sudo: I live on Windows, no idea ;) But if some users need it, removing might not be a good idea.

[raphinesse]

@janpio I think I don't get your point

[ttimmy]

Hello. Got here after I ran into problems installing cordova on Ubuntu Xenial LTS. This issue is currently labeled as "enhancement," and I think it should be escalated to an actual bug in the documentation.

Following the instructions on installing cordova using sudo on Ubuntu doesn't work. I installed a fresh Ubuntu 16.04 machine in VirtualBox (Node 10), and here is what happens when trying to create the HelloWorld project:

cordova create hello com.example.hello HelloWorld

/usr/lib/node_modules/cordova/node_modules/insight/node_modules/configstore/index.js:53
				throw err;
				^

Error: EACCES: permission denied, open '/home/ubuntu16/.config/configstore/insight-cordova.json'
You don't have access to this file.

    at Object.openSync (fs.js:438:3)
    at Object.readFileSync (fs.js:343:35)
    at Configstore.get (/usr/lib/node_modules/cordova/node_modules/insight/node_modules/configstore/index.js:34:26)
    at new Configstore (/usr/lib/node_modules/cordova/node_modules/insight/node_modules/configstore/index.js:27:45)
    at new Insight (/usr/lib/node_modules/cordova/node_modules/insight/lib/index.js:38:34)
    at Object.<anonymous> (/usr/lib/node_modules/cordova/src/telemetry.js:26:15)
    at Module._compile (internal/modules/cjs/loader.js:701:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:712:10)
    at Module.load (internal/modules/cjs/loader.js:600:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:539:12)

I tried to install without sudo and:

ubuntu16@ubuntu16-VirtualBox:~$ npm install -g cordova
npm WARN checkPermissions Missing write access to /usr/lib/node_modules
npm ERR! path /usr/lib/node_modules
npm ERR! code EACCES
npm ERR! errno -13
npm ERR! syscall access
npm ERR! Error: EACCES: permission denied, access '/usr/lib/node_modules'
npm ERR!  { [Error: EACCES: permission denied, access '/usr/lib/node_modules']
npm ERR!   stack:
npm ERR!    'Error: EACCES: permission denied, access \'/usr/lib/node_modules\'',
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'access',
npm ERR!   path: '/usr/lib/node_modules' }
npm ERR! 
npm ERR! The operation was rejected by your operating system.
npm ERR! It is likely you do not have the permissions to access this file as the current user
npm ERR! 
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator (though this is not recommended).

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/ubuntu16/.npm/_logs/2019-03-19T22_22_56_331Z-debug.log

I tried searching this project for "EACCES" and "cordova-insight" to see if I'm the only one with this problem. I found no results, but since this is a brand new Ubuntu setup I don't think it's just on my end. I'm finding a lot of stuff in stackoverflow about sudo, npm and permissions. So I'm aware there is an issue here, but I think the docs should either have a working set of instructions, or at least mention that installing on Ubuntu is currently not officially supported.

The docs have a paragraph about npm and sudo, but the link to "more tips" directs to justjs.com, which is no longer active.

Reading this issue, I can understand that there is an alternative (npx) which I'm going to read on now. As I said in the beginning, I'm posting this because I think this should be escalated from "enhancement" to something more.

Thanks for all the hard work!

P.S. I wanted to upload the screencast of installation, but Github only accepts GIFs, so hope this helps:

Edit: P.P.S: I tried a new Ubuntu installation again, but this time installed npx. I'm listing the steps here in case anybody comes here looking for answers. After installing Node (current LTS is 10), run the following:

sudo npm install -g npx

Next, try to create the cordova project via npx (you will get an error):

npx cordova create hello com.example.hello HelloWorld

Follow the error's instructions on changing permissions on your .config folder (the command sudo chown...). I can't paste it for you here because the path varies according to your home folder name. Now try creating the project again:

npx cordova create hello com.example.hello HelloWorld

After being asked about telemetry permissions, you'll be good to go. Just use npx cordova instead of cordova from now on. Disclaimer: This worked for me and it got the project created. Try creating platforms, building, debugging etc. your project before relying on this any further.

If the maintainers of the docs approve, I suggest creating a link to this issue (and in particular this comment) to replace the old broken link ("more tips") that exists in the docs now.

[raphinesse]

@ttimmy thanks for the detailed report.

We indeed have to improve the docs in this area, but I'm not sure if it qualifies as a bug in the Cordova docs since the actual problem you encountered is more due to a bad npm setup. Unfortunately, the defaults that Ubuntu provides don't work that well. I would suggest a setup that installs global packages to your home directory so you won't have to use sudo to install packages globally. I can't provide a link on how to do that right now, but I think we should provide that in the docs too.

[ttimmy]

@raphinesse thanks for your reply, and I agree the docs should reflect this issue with Ubuntu. As it stands now, the docs do not apply "out of the box" with Ubuntu (extra steps need to be taken.)

I suggest adding your paragraph to the docs until a permanent solution is established: Unfortunately, the defaults that Ubuntu provides don't work that well. [We] suggest a setup that installs global packages to your home directory so you won't have to use sudo to install packages globally. See [here](https://github.com/apache/cordova-docs/issues/838) for more info.

If we put ourselves in the shoes of an inexperienced developer who wants to use the power of cordova (which is cordova's major strength IMO), he/she will be confused when trying to follow this guide as it is right now.

[janpio]

For Windows uses I usually suggest the usage of nvm-windows when there are any problems with npm/node - that usually solves or works around the issue. Would that maybe also be a solution for Ubuntu (with nvm of course)?

[raphinesse]

@janpio I usually have only a single-version node setup on my machine and use npx to test with other versions if necessary. But AFAIK nvm is completely installed to the user's home dir by default and that's a good thing IMHO.

But I don't think that we should go into any detail regarding the user's Node.js setup in our docs. I'd prefer a link to some comprehensive resource on the topic.

[raphinesse]

Possible resource to link to: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm

[dblotsky]

I don’t think we should be recommending npx to users because it incurs a heavy performance overhead, relaxes security, and increases the number of points of failure at each invocation of cordova.

[jcesarmobile]

I think if you locally install Cordova per project, then there is no performance overhead when using npx to run cordova command

[dblotsky]

Even if you omit the performance overhead, the other two issues remain unaddressed.

[brody4hire]

I am also not so enthusiastic about directing people to use npx cordova for multiple reasons.

I think the Cordova CLI is a bit big for this kind of usage, especially at the stage when someone starts a new Cordova project.

The Cordova CLI behavior can change over time, major one has been what is configured in config.xml vs package.json which does not seem to be as consistently synchronized starting with Cordova 9.

Also seems to be a bit extra to type out for every operation that is done on the project.

I think it would be ideal if we could find a way to break the Cordova CLI into smaller, simpler tools. Just like someone could do create-react-app or react-native init, and then use npm package scripts to do the rest.

P.S. I would favor that we document in 1 or 2 places that the app developer can always do npx cordova in place of cordova if s/he does not want to use a global Cordova CLI installation. I think this should be pretty clear.

[ttimmy]

@brodybits Hey Brody, big fan of your SQLite plugin, cheers.

Just chiming in here about your postscript, since I've been advocating for exactly that. As the docs stand right now, Ubuntu installations of cordova fail due to the global installation requirement. In fact, Cordova 9.x has been released, and the create new app page still has a paragraph about Linux that has a broken link (justjs.com is broken.) That is why I suggested to change this issue from an enhancement to a bug, but that's just my opinion based on my very limited technical knowledge of Cordova itself.

[dblotsky]

UX aside, I still think npx greatly relaxes security, and increases the number of points of failure at each invocation of cordova (e.g. when there are typos). I think recommending its use is a serious disservice to users.

[robations]

Worth revisiting this issue? People have been saying for years not to use sudo for global npm installations because it can allow unknown install scripts to run as root on your dev machine (presumably for anything in the dependency tree for your install target). I was fairly surprised to see it in official cordova docs.

Even just removing sudo from instructions would be an improvement, putting aside arguments for/against npx.

[jcesarmobile]

now npx asks if you want to install the package before executing the command (if it's not already installed), so if you mistype the command it won't run anything unless you approve to install the mistyped package

[breautek]

Worth revisiting this issue? People have been saying for years not to use sudo for global npm installations because it can allow unknown install scripts to run as root on your dev machine (presumably for anything in the dependency tree for your install target). I was fairly surprised to see it in official cordova docs.

Even just removing sudo from instructions would be an improvement, putting aside arguments for/against npx.

Agreed 100%. NPM also have guides for installing npm in a way where it doesn't require sudo access, which we could have a note linking to on our Setup page. There is already a note on how to get sudo-less access, but links to a non-existent page currently.

[erisu]

Closing as completed: #1313

Guide was updated and removed sudo. However, we left a brief explanation of when sudo might still be needed. At the end, we said it is recommended to use a version manager to avoid using sudo and the potential consequences associated with sudo.