Official Native Module Directory

[stmoy]

Introduction

One of the most important components of React Native is the ability to access native platform APIs. Even better: the vast React Native community has built and shared common "native modules" to handle everything from camera support to Bluetooth capabilities to authentication.

There are a dizzying array of native modules - each with a different array of capabilities, contributors, and quality. How is a RN developer expected to find the most appropriate module for their scenario? How can they know that the native module that they are using will work for their app/scenario/endpoints? How can they know that the module is actively being maintained?

The Core of It

There is not a single "officially sanctioned" directory of community modules. This means that developers must search to find high quality native modules. Providing an official directory of modules takes the burden off of the end-developer and enables them to confidently build experiences using modules that they know will work.

TL;DR - I propose we update and endorse Native.Directory as React Native's "official" native module directory. The text that follows describes why and how.

Q: Do any module directories exist already?

There are several community-driven module directories, including:

• Native.Directory
• prscX/awesome-react-native-modules

These directories each have their own pros and cons:

Native.Directory

Pros

• Searchable, filterable website front-end
• Simple "1-100" quality ranking
• Shows compatibility info for iOS, Android, Expo, Web
• Community can add missing libraries

Cons

• Simple "1-100" quality ranking doesn't indicate how quality is calculated
• Does not include compatibility info about Windows, MacOS

prsX/awesome-react-native-modules

Pros

• Organized by scenario/usage (ie. UI, Loaders, Prompts, etc.)
• Has links to tutorials/setup/get started
• Large list of modules and descriptions for each
• Community can add missing libraries

Cons

• Difficult to navigate/search
• Limited compatibility info: just iOS, Android
• Single contributor/owner (prscX)
• Relatively unknown - 14 Watchers, 316 Stars, 41 Forks

Q: How does Native.Directory define "quality"?

Native.Directory provides a "quality" score from 1-100. The methodology is determined by the following formula.

It includes both aggregate and raw data, such as:

• How many issues are on that GitHub repository
• Popularity (Subscribers, forks, stars, downloads)
• License (vs none)
• Updated recently (or not)
• Recommended*

* Note: the "Recommended" field seems to be subjective and set by @brentvante

Native.Directory does not include the following as part of its quality score:

• Number of supported platforms
• Test coverage
• CI loop support

Q: Why have an "officially sanctioned" directory at all?

As more parts of React Native get splintered out into the community, it will become increasingly important that React Native developers are able to find high quality native modules that meet their needs. We (at MSFT) have also heard from partner teams both internal and external that they would prefer to have a list of known high-quality modules so they are quickly able to determine which modules are available.

I don't believe that the RN Core platform team needs to be responsible for curating the list of modules - the community directories already do a good job of this. Instead, I propose we elevate an existing directory by linking/advertising it as the "Official React Native Module Directory" even if it is maintained by the community.

Q: Won't the react-native-community repo naturally provide a directory of modules by virtue of being within react-native-community?

Probably not.

Issue #176 discusses which packages belong within react-native-community. Some of those packages are the ones that were initially in core and are moving out, some are the packages that support those modules, and some (maybe) are modules that are important to the ecosystem.

However, there are a set of important and commonly depended on modules that currently live (and likely will continue to live) outside of react-native-community, like Expo and react-navigation. The directory will need to surface these modules as well.

Q: What about Turbo Modules?

The introduction of Turbo Modules will require changes to community modules. Whatever we build or modify should provide information about if the module has been written to support Turbo Modules.

Note: Turbo Modules are the future, but they also haven't been formally released yet. It is unclear to me what their impact will be on community modules. I'd love help figuring out this space, as this is a "known unknown" for me.

Q: What is being proposed?

I'm proposing that we update and elevate Native.Directory in the following ways:

• Update Native.Directory to become aware of and expose information about the missing quality metrics, including:
  • Out of Tree Platforms (Windows, MacOS, etc.)
  • Test coverage
  • CI loop support
  • Turbo Module support
• Reconsider the way that the "quality" metric is displayed - either remove it, or add a note about how it is calculated
• Link to Native.Directory from the official Native Module guidance docs

Discussion points

• Are there other community-driven directories that are missing from the above list?
• How should the directory display information about Turbo Modules?
• Is the Native.Directory "quality score" a useful thing to display? On one hand, it provides an easy "single number" to help rank all of the modules automatically. On the other hand, it is a black box that may or may not represent the actual quality of a module.

[elicwhite]

Thanks for posting this with so much thoughtful detail.

Here is a non comprehensive reply. ;)

I'd love to see native.directory embedded in the official docs, so it feels the same way Gatsby's plugin search does for Gatsby: https://www.gatsbyjs.org/packages/gatsby-image/

Also, cc @brentvatne as the current owner of native.directory.

[brentvatne]

Thanks for putting this together @stmoy! I'm really excited to get to a place where we have an agreed upon single source for exploring React Native packages.

Are there other community-driven directories that are missing from the above list?

js.coach is another one. I think the UI is quite pleasant, and we could take some inspiration from it for native.directory. They also have a compatibility option for Windows - I'm not sure where that data comes from though.

How should the directory display information about Turbo Modules?

I don't have a strong opinion about this, perhaps it's worth listing possible ideas. I'll list some of the first ideas that come to mind (kind of like the McDonald's theory)

• Factor TM support into the score
• Add a badge/filter for TM support

Is the Native.Directory "quality score" a useful thing to display? On one hand, it provides an easy "single number" to help rank all of the modules automatically. On the other hand, it is a black box that may or may not represent the actual quality of a module.

Maybe we could make it easy to inspect 1) how this is calculated generally 2) how the score for a particular module was arrived at. A single number will never tell the whole story but I think it's still valuable as a heuristic.

[kelset]

Thanks for starting this conversation @stmoy!

I like how Brent has phrased this topic

single source for exploring React Native packages

Instead of using the wording "official".

I'll dive into that a bit more in a sec*; before that, to quickly reply your questions:

Are there other community-driven directories that are missing from the above list?

I think that the only one not being mentioned yet is -> https://github.com/jondot/awesome-react-native which has basically the same pros&cons as prscX's.

How should the directory display information about Turbo Modules?

I agree with Brent on this, a badge is probably enough. Maybe clicking on it could lead to a D&P issue on more details on the TB "support" - like, if something similar was added for AndroidX, we could link to #129

Is the Native.Directory "quality score" a useful thing to display? On one hand, it provides an easy "single number" to help rank all of the modules automatically. On the other hand, it is a black box that may or may not represent the actual quality of a module.

I think it'd be helpful to quickly glance through the list. But yes, there should be a "transparency" section where it's explained how it's calculated (also, because in the past I think I've found a bug with that implementation which was caused by the GitHub API v3... issue: react-native-community/directory#20 ).

---

/* let me dive a bit more on the "official" word.
In particular, this phrase:

linking/advertising it as the "Official React Native Module Directory" even if it is maintained by the community

has both my main concerns on this topic.

1. the word official adds a lot of "weight".

In the past there have been a few instances of members of the community actively expecting more from any library listed "it's on the official list, why is this XXX feature missing?!?". Simplest examples of this are all related to navigation libraries.

Similarly, this can lead to polarisation in the community: in one case a person opened a PR to fully rewrite the doc page on navigation to basically highlight an "N+1 library" compared to all the others - and when the PR was getting reviewed and the maintainers tried to make this person use a more balanced approach the PR author basically started flaming claiming they were censored and stuff.

Given that in native.directory the list of repos can be easily modified and it's not per se enforcing opinions on the repos listed (that's sort of indirectly done by the score), I feel this overall issue may be "softened" but I fear will still be presented. Avoiding the word "official" may help with that too.

2. someone will still have to maintain this project

Saying that it will be maintained by the community kind-of "hand-waves" over the fact that a group of people (from the community) will have to maintain this entry point. I fear it can be quite a mental burden, and in particular if there is ever a case where they will have to reject a PR to add a library to the list I'm quite concerned of how stressful it may turn.

So, I guess, my TL;DR of this would be:

I think embedding native.directory somehow in the main react-native website could be the way to go, but let's present it as more of a neutral tool for searching/exploring packages then an "officially curated list" to remove risk of friction.

[elicwhite]

If native.directory was put into the docs I’m not sure I like that it is a curated list. Would it be reasonable for it to include all npm packages that have react-native in the name, or a tag of react-native?

[jonsamp]

Is the Native.Directory "quality score" a useful thing to display? On one hand, it provides an easy "single number" to help rank all of the modules automatically. On the other hand, it is a black box that may or may not represent the actual quality of a module.

Regarding this question, I think the singular score is really helpful on an overview/search page. The part we're missing in native.directory is having a detail page (or dropdown) that has more details. This is just a rough sketch (super open to feedback), but i think we could display the different components of the score in a format like this, once you've clicked into a specific package:

I just picked random quality labels. The idea is that it would read like a receipt where you'd see an itemized list of things that add up at the bottom to the overall score.

---

In general, I also support making native.directory the source of truth for finding packages, and will contribute to improve it.

[timomeh]

Is the Native.Directory "quality score" a useful thing to display? On one hand, it provides an easy "single number" to help rank all of the modules automatically. On the other hand, it is a black box that may or may not represent the actual quality of a module.

I really dislike that quality score bar and I would love to see it completely go away. I don't think it sends the right message, and I dislike the way it attaches a global score to all modules.

First of all, "quality" isn't a good word for it. It's a word which should be used carefully. When I first saw that bar, I thought it meant code quality and I was bummed that the code quality bar of my module was only half filled.

Measuring "quality" with factors like popularity and open issues is really bugging me. A module isn't better because a bot closes real issues if nobody responds to them in a month. A module isn't bad because it's a niche topic and thus less people are using it and it's less actively maintained. It's not a sign of bad quality if a Maintainer decides to make his module feature complete and thus there are no recent commits.

If you are directly comparing competing libraries: take a look at them! Do your research. Read through their documentations. Maybe you like one API better than the other. Check if there are any severe issues. Are there a lot of open PRs and people want to merge it but the Maintainer isn't responding? Or just use one of them and try it out.

That's a skill every developer needs to learn. And sometimes you install a library, you play around with it and you notice that it just doesn't feel right – time to try an alternative. It can feel frustrating to spend two hours with a library and then remove it, but that's part of our job.

No automatically generated score can and should prevent this.

I believe that showing any other subjective "positive" metric like test coverage or existence of CI will be controversial because it's subjective how much they matter. It's fine to show objective metrics (Stars, Downloads, Platform compatibility), but then you are just mirroring data and are now concerned with having up-to-date data.

Why show those metrics in the first place? I never experienced a situation where I was looking for a React Native module and was so overwhelmed with the amout of modules for one use case that I needed to sort and filter them by such criterias. My problem is discovering them in the first place.

What I would like to propose

I really like the idea of an official module directory, but I don't think there's much benefit in another listing of modules. I would love to see native.directory focus on the community, guide new developers to some common modules and explain why you could need them, let me explore new or trending modules, be a place where you want to browse through all the stuff the community made.

[jonsamp]

Thanks @timomeh for your comments on this. I think you brought up a lot of good critiques.

First of all, "quality" isn't a good word for it. It's a word which should be used carefully.

I agree that "quality" attaches too much value to what this is. Perhaps there's another word we can use that's less ambiguous and without as much weight. First things that come to mind are "score", "directory score", "first impression score".

If you are directly comparing competing libraries: take a look at them! Do your research. ... That's a skill every developer needs to learn.

You're right, this is definitely a skill developers must learn, however not all developers know what to look for or they haven't learned yet. We have an opportunity to help less experienced developers and non-developers understand some aspects of what an experienced developer might look for. And if you're an experienced developer, chances are you might see the score and it won't matter because you're going to do research based on your specific need/context anyway.

And sometimes you install a library, you play around with it and you notice that it just doesn't feel right – time to try an alternative. It can feel frustrating to spend two hours with a library and then remove it, but that's part of our job. ... No automatically generated score can and should prevent this.

We should make it clear that the score is not trying to achieve this goal. I think the goal of this score is to show data of things an experienced developer might look for at first glance.

...guide new developers to some common modules and explain why you could need them, let me explore new or trending modules,

Yes, I support this idea a lot!

---

Here's how I think the "quality" score could be made to work:

1. Rename it to something else that assigns it less quality, and more that it's an impression we auto-generated.
2. Don't show a combined score in search results. Only show the full scoresheet if you click into a package to see more details.

---

Other stuff:

• The native.directory's design is cool, but I think we have an opportunity to make it more usable with visible elements like checkboxes/input fields. Happy to help with this!
• It'd be great to have some curated lists/short guides on how to do a couple common things.
• Make "add/update your package" a bigger CTA.

[timomeh]

@jonsamp I agree with your points. And you're right, listing notable aspects of a module is also a good learning resource.

[elicwhite]

What's the path for taking action on this proposal? What are the steps that should be taken to make progress towards this being a reality?

[EvanBacon]

As someone working on web support, I'd personally like to see something like https://caniuse.com/ for React Native. Whatever interface is decided on should have a way to track in-progress and partial support.

[harinikmsft]

@EvanBacon - that looks pretty interesting. Riffing off of that, summarising what's been discussed so far and addressing @timomeh's feedback - perhaps, the interesting data for customers of modules is not a mysterious quality number driven curation of modules, but a searchable/filterable list of any/all react-native module with a checklist of objective data about each module that could contribute to high quality.

This checklist could be everything discussed so far, like:

• Is it a pure JS module (or) does it have native code?
• Which devices/platforms does the module support?
• Which versions of RN does the module support?
• Does this module have unit tests?
• Does this module have E2E tests?
• When was it last updated?
• What's the npm download stat? (Current year, over time)
• What's the OSS repo engagement stat?
  etc.,

Not all parameters are interesting to all customers. This way, we completely side-step defining one quality bar, but let people decide for themselves which aspects are important for their use cases. The more objective this can be, the more automated we can make it as well.

@TheSavior - regarding next steps: if the approach above sounds reasonable, @stmoy could make the checklist more concrete and we could use some help from community members in actually setting this website up.

[elicwhite]

I agree that I think this needs to be a list of all react-native related packages, not a manually curated list. That approach sounds reasonable to me. I'm not super worried about having all the details figured out here first, I think that can be iterated as things move along.

[brentvatne]

@TheSavior - i think listing all packages is great but i'm not sure i think it's good to harvest them automatically from npm based on tags or some naming convention. in practice native.directory isn't actually "curated" in the sense of filtering out things that don't fit some subjective criteria - we accept submissions for any library that people want to add to it, the key thing is that someone thinks it's good enough to be listed and takes the time to fill out some information about compatibility that isn't easily answered by looking at any npm package data.

[elicwhite]

Having to manually manage that seems like a lot of work. Especially if Microsoft wants to add more axis like Ci. If that data isn’t harvested automatically then someone would have to go through all existing submissions, right?

[andrioid]

AFAIK the Gatsby Plugin directory has a tag that you have to add to your npm package to be listed.

Why not do the same, and then also manually add until that works?

[brentvatne]

Having to manually manage that seems like a lot of work. Especially if Microsoft wants to add more axis like Ci. If that data isn’t harvested automatically then someone would have to go through all existing submissions, right?

yeah, or if it isn't explicitly labeled then it's marked as unknown. i'm not sure how else we can identify these factors without manually tagging them

[oblador]

It would be possible to collect most of it by inspecting the git repo/package contents with some heuristics. But also, why couldn’t we do a hybrid? Meaning do best effort by scanning npm/repo contents and then open up for manual edits from visitors.

[brentvatne]

there are a few separate topics here when it comes to getting packages on the directory, i'll call them find, curate, evaluate.

💡 in the following sections i use the word "bad" to describe packages that are broken, unmaintained, malicious, or some other thing like that. it's an easy placeholder for word for packages that should not be surfaced to the community because their use will lead to a bad experience.

🤔 i know curate sounds snobby but i just mean filtering out bad packages

---

1. find: how do we find all react-native packages on npm?
2. curate: how do we filter out bad packages?
3. evaluate: how do we analyze the package to know which of the criteria that the users care about are satisfied by it?

find

• this can be done in an automated way, for example by asking folks to tag their packages in their package.json.
• it can be done manually by having the authors or other folks in the community submitting an entry for that package as a pull request.

curate

• to filter out bad packages when they are found automatically we would need to manually maintain a block list.
• to filter out bad packages when they are added manually we would just need to reject a pull request, or more likely they will not be submitted for the directory.
• over time if packages become bad, we would need to add to block list / remove from package repo.

evaluate

• most things that we discussed here can be derived automatically by knowing the npm package name and github repo url. some things can't be reliably known from this currently, without establishing better conventions, eg: what platforms are supported? does it work in expo managed workflow? what versions does it support?
• once we gather a list of properties that we would like to know about each project we should categorize them as whether they are currently knowable or not via analysis of github / npm. for those whose value we cannot derive from those sources we should consider whether we should add some conventions to package.json (or elsewhere?) where the author can provide this metadata. in some cases, it may be reasonable to track the metadata only on native directory (eg: if we have some equivalent of flutter favorites).

summary / to dos

• decision - automate or manual submissions for find? do we want to set up a crawler to find react-native packages on npm and a blacklist to filter out bad ones, or have folks submit their packages to native directory?
• collect and categorize evaluation criteria: list everything we want to know about a package and whether we can automate populating it by analyzing github/npm

[jonsamp]

Since part of this discussion is about design, I made a rebranded design mock of the react native directory and posted it in the thread regarding design here: react-native-community/directory#190 (comment)

I'd love your feedback on it!

[molant]

Hello all 👋

I've been talking with RN devs from different backgrounds to get some insights about how to improve the experience in general (let me know if you'd like to participate in this research!).
One of the topics we talk about is their process to choose a third party component.

The common criteria so far is (except platform support, the others are in no particular order):

• Platform support: iOS, Android, web, Windows, etc.
• Issues: how many open issues? how long does it usually take to close them? are there many stalled ones? are people working on them? Same for PRs
• API shape: do they like the API? Does it use promises, etc.?
• Documentation: does it have any? Is it up to date?
• Versions: How often do they update? How long to support a new version of RN?

In general they assume there's always going to be some trade-offs no matter which one they choose.

[stmoy]

Following up and next steps

First: a 🥳 big thank you to everyone who contributed to the above conversation. Your ideas have helped inform the next steps that are outlined below.

@TheSavior @harinikmsft @jonsamp @brentvatne @hramos and I met to chat about what we'll do next.

At a high-level, it seems like there are three main areas of investment for native.directory: Discoverability, Usability, and Visibility.

• Discoverability: How can we get folks using reactnative.directory as part of their workflow?
• Usability: How can we improve reactnative.directory to make it more useful?
• Visibility: How can we update reactnative.directory to visually indicate which out-of-tree platforms (like Windows, Mac) are supported?

In each of these categories, we have [short-term] goals and [long-term] goals:

• Discoverability:
  • [short-term] Update name from native.directory to reactnative.directory
  • [short-term] Ensure the directory is linked from the official docs
  • [long-term] Update the branding of the directory so it can more easily “slot into” the official docs
  • [long-term] Integrate the directory into the official docs
• Usability
  • [short-term] Show to users how the quality score is determined
  • [long-term] Integrate other quality metrics such as CI loop, unit tests, E2E tests, etc.
  • [long-term] Integrate into the official search
  • … others?
• Out of Tree Platforms:
  • [short-term] Add Windows/Mac as platform options
  • [short-term] Identify which modules should “just work”

There were also a set of docs that would be useful to have:

• Overview of extensions
• Auto-linking guide
• Native vs. JS only modules guide

Next Steps

@brentvatne:

• Migrate to reactnative.directory from native.directory
• Add “Windows” and “Mac” as fields in reactnative.directory
• Write a high-level doc for using packages (and a link out to reactnative.directory) with the goal of getting this doc added to the official RN docs

@jonsamp:

• Continue to iterate on the design, including thinking about how to call out the quality metric

@stmoy:

• Compile a list of JS-only modules that should “just work” with Windows, Mac so that they can be validated and marked on the directory

If there is anything I missed, please let me know!

[plrdev]

The score reminded me on something that I found useful while finding libraries for Flutter at pub.dev. They have something like this:

I found this to be quite helpful to get a quick sense of whether a library is worth checking more into and something similar would provide value in here as well.

Here is how they explain their https://pub.dev/help#scoring formulas.

[brentvatne]

https://reactnative.directory/ is live and being actively worked on by @Simek, @jonsamp, myself, and occasionally some others! we link to it from https://reactnative.dev/ in various places and I think it's in a pretty good place, so I'm going to close this discussion so we can continue to more focused discussions on https://github.com/react-native-directory/website