diff --git a/research/name.md b/research/name.md new file mode 100644 index 0000000..76399d9 --- /dev/null +++ b/research/name.md @@ -0,0 +1,52 @@ +# Name + +Analysis of the `name` property + +## Analysis + +- The `name` and `version` together form an identifier that is assumed to be completely unique[1] + - In practice, the unique identifier for a package is also comprised of its registry. It is valid to have two packages with the same `name` and `version`, except one must be aliased so that the package manager can correctly resolve its registry value. +- The `name` property is optional if the package will not be published.[1] + - Generally, it is also best practice to specify the [`"private": true`](./private.md) property so that the package is not accidentally published. + - > [TODO: Is `name` actually optional?](https://github.com/openjs-foundation/package-json-research/issues/9) +- It must be less than or equal to 214 characters (including scope)[1] +- The names of scoped packages can begin with a dot or an underscore. This is not permitted without a scope.[1] +- It cannot contain uppercase letters[1] + - Historically, uppercase characters were allowed, but npm enforces all new packages are lowercase only[1] +- It must contain only URL-safe characters[1] + - > [TODO: What are "URL-safe characters"?](https://github.com/openjs-foundation/package-json-research/issues/4) + > - Is this based on the WHATWG URL specification or something else? + > - Relevant stackoverflow: https://stackoverflow.com/questions/695438/what-are-the-safe-characters-for-making-urls + > - Is the validation for this in the npm cli open-source? + +### Scope + +- While all packages have a name, some also have a scope.[2] +- A scope follows the same rules as a name (URL-safe characters, no leading dots or underscores).[2] +- When used in package names, scopes are preceded by an `@` and followed by a `/`. + - Example: `@scope/pkg`[2] + +## Platform Specific Behavior + +### npm + +- Installing a scoped package saves it to the scoped folder by the same name (including the `@`, excluding the `/`).[2] + - Example: Both `@scope/pkg-1` and `@scope/pkg-2` would be installed to the `node_modules/@scope` directory. +- If the `@` is omitted, npm will automatically attempt to install the package from GitHub.[3] +- All npm users have their username reserved as a scope.[2] + - Example: User `jack123` has the scope `@jack123` reserved specifically for themselves. +- Similarly, npm requires other scopes (non-username) to be registered first as an npm organization, then permitted users of that organization can publish to that scope.[2] +- Scopes can be associated with a registry.[2] + - `npm config set :registry ` or `npm login --registry= --scope=` (`` must include the `@` symbol). + - One scope must only ever point to one registry. + - One registry can host multiple scopes. + +## Sources + +1. [npm `name` field documentation][1] +2. [npm _Scope_ concept documentation][2] +3. [npm `install` command documentation][3] + +[1]: +[2]: +[3]: diff --git a/research/package-json.md b/research/package-json.md index 51151b4..7d64c31 100644 --- a/research/package-json.md +++ b/research/package-json.md @@ -4,5 +4,7 @@ - [`"dependencies"`][dependencies] - [`"devDependencies"`][dependencies] - [`"peerDependencies"`][dependencies] +- [`"name"`][name] -[dependencies]: <./dependencies.md> "Dependencies" \ No newline at end of file +[dependencies]: <./dependencies.md> "Dependencies" +[name]: <./name.md> "Name Property" \ No newline at end of file