Getting Published

Step 1: Provide good documentation and metadata

Readme

Add a file named README.md to the root of your project. A good readme should at the very least answer the following questions:

  • What is it?
  • What state is it in?
  • How do I install it?
  • How do I use it?

Furthermore, providing an example, a change log and explaining how to contribute is a bonus. And if it is a binding, please provide a link to the bound library, as it usually provides more in-depth information and documentation.

NOTE: The readme and other metadata together must total less than 10k bytes in order to be indexed by the search engine. To avoid going over that limit, please keep the contents of the readme to only the essentials, and put extensive documentation and such in a separate markdown file linked to from the readme. This also has the added benefit of improving search relevance., making it easier to find your package when searching for relevant terms.

Metadata

Fill out the following fields in package.json:

  • description - A short sentence describing the package
  • license - The SPDX License ID of the package license
  • keywords - A list of keywords describing the package
  • homepage - The URL of the project homepage
  • repository - The URL of the source code repository
  • bugs - The URL of the bug tracker

Additionally, a number of other factors are taken into account when calculating a score for the package, which primarily is used as part of search result ranking. This data is blatantly stolen from npms.io, who are nice enough to detail the factors taken into account here.

Step 2: Publish to NPM (optional)

Follow the documentation on NPM

Publishing to NPM is not a requirement. If your project is incomplete, experimental or otherwise not yet ready for primetime, it might be easier to just depend on the master branch of the source code repository. You can still submit your package to redex, where it'll then be marked as unpublished. This is not only intended as a warning, but also to highlight opportunities to contribute.

Step 3: Submit to redex

Submitting published and unpublished packages both follow roughly the same process: Add the package to the appropriate collection in sources.json and submit a PR. Or just submit an issue with the same information.

Published package

Add an entry in the published collection with the follwoing format: 

"<npm name>": {
  "category": "binding" | "library" | "tool" | "boilerplate",
  "platforms": ["browser" | "node" | "native" | "any"],
  "keywords": [<string>]
}

Unpublished package

Add an entry in the published collection with the follwoing format: 

"<owner>/<repository>": {
  "repository": "github:<owner>/<repository>"
  "category": "binding" | "library" | "tool" | "boilerplate",
  "platforms": ["browser" | "node" | "native" | "any"],
  "keywords": [<string>]
}
Submissions are checked manually (with a little help from a linter script). Any remarks will be noted in the PR. There's also a CI process that checks sources.json for syntax and trivial errors, which will quickly fail if you just made a silly mistake.

Frequently Asked Questions

  • What does the "neglected" flag mean?

    Packages that do not meet the minimum standards for documentation and metadata, according to what's described in Step 1 above, are marked as neglected. These packages might still function perfectly well, which is why they're listed at all, but the quallity of the packaging is also often a good indicator of the quality of its contents. There are therefore two for having this, and to de-emphasize flagged packages:

    1. When there are alternatives, it makes it easier for consumers to make a choice by discarding packages that present themselves poorly and make unnecessarily hard to make an informed choice.
    2. It serves as an incentive for package authors to improve the presentation.

  • Which keywords can I use?

    Please try to use only the keywords that are already in use, which are listed on the front page. If you don't think you package fits into any of these categories, you may propose a new keyword in the submission PR.

  • What does the "any" platform mean?

    The "any" platform means the package is platform-independent, because it avoids using platform-specific features. It's improtant to distinguish a package that is platform-independent from a package that, in one way or another, targets all avilable platforms. These are not equivalent since a platform-independent package will automatically support any new platform.

Project

Made with

Reason