doc: How to publish N-API packages #13107
Conversation
| @@ -0,0 +1,27 @@ | |||
| ## To publish an N-API version of your package alongside your non-N-API version | |||
| The following steps are illustrated using the package `iotivity-node`: | |||
There was a problem hiding this comment.
Nit: can you please add an empty line before this one?
| Tagging the release with `n-api` has ensured for `iotivity-node` that, although version 1.2.0-3 is later than the non-N-API published version (1.2.0-2), it will not be installed if someone chooses to install `iotivity-node` by simply running `npm install iotivity-node`. Thus, the non-N-API version will be installed by default. The user would have to run `npm install iotivity-node@n-api` to receive the N-API version. | ||
|
|
||
| ## To introduce a dependency on an N-API version of a package | ||
| For example, to add the N-API version of `iotivity-node` to your package's dependencies, simply run `npm install --save iotivity-node@n-api`. Thus, you will receive version 1.2.0-3, which is the latest N-API-enabled version of iotivity-node. The dependency in your `package.json` will look like this: |
|
|
||
| ## To introduce a dependency on an N-API version of a package | ||
| For example, to add the N-API version of `iotivity-node` to your package's dependencies, simply run `npm install --save iotivity-node@n-api`. Thus, you will receive version 1.2.0-3, which is the latest N-API-enabled version of iotivity-node. The dependency in your `package.json` will look like this: | ||
| ```JSON |
| ``` | ||
|
|
||
| Note that, unlike regular versions, tagged versions cannot be addressed by version ranges such as `"^2.0.0"` in your `package.json`. The reason for this is that the tag refers to exactly one version. So, if the package maintainer chooses to tag a later version of their package using the same tag, you will receive the later version when you run `npm update`. This should be acceptable given the currently experimental nature of N-API. If you wish to depend on an N-API-enabled version other than the latest published, you must change your `package.json` dependency to refer to the exact version on which you wish to depend: | ||
| ```JSON |
| ## To publish an N-API version of your package alongside your non-N-API version | ||
| The following steps are illustrated using the package `iotivity-node`: | ||
| - First, publish the non-N-API version: | ||
| - Update the version in your `package.json`. For `iotivity-node`, the version becomes `1.2.0-2`. |
There was a problem hiding this comment.
We have always treated guides as being less formal in style, but I've been wanting to move away from that, starting with avoiding the use of personal pronouns (you and your, etc) in the documentation.
There was a problem hiding this comment.
Also, minor nit but can you line wrap at <= 80 chars
|
Is |
1. Added empty lines as suggested 2. Removed use of personal pronouns 3. Line wrap <= 80 chars
| ``` | ||
|
|
||
| Note that, unlike regular versions, tagged versions cannot be addressed by | ||
| version ranges such as `"^2.0.0"` insside `package.json`. The reason for this |
There was a problem hiding this comment.
fixed this in the new PR nodejs/nodejs.org#1236
Thanx!
|
I think we should put this in https://nodejs.org/en/docs/guides/ since it seems to be more user-facing vs core. I'm looking forward to seeing this become the standard though :] |
Agreed, @aruneshchandra would you mind submitting this against nodejs.org locale/en/docs/guides instead? That way hopefully more people outside core will find this. |
|
Seems reasonable to me as well to publish on nodejs.org. @aruneshchandra if you can post the new PR here, we'll jump over and complete the review there. |
|
Opened a new PR nodejs/nodejs.org#1236 |
|
Hey, what files should be published in npm? build files also or it will be generated while installing? |
10 participants
Checklist
Affected core subsystem(s)
doc