Making a "Lovable" Module

lovable.md

Lovable

Lovable modules maximize developer trust.

To learn how to maximize trust, I studied developers I trust and some of their most popular modules. It's no coincidence that I ended up using some of their modules to build mine!

Dependencies

Dependencies introduce friction. Most of the modules I trust have a small number of dependencies (including siblings). This makes sense. Removing dependencies from your module will remove friction of adoption. I decided that my first lovable module should have zero dependencies.

1. There's less to maintain for the module's developers, so they're more likely to keep it up to date. This is especially important around server modules, frameworks, or crypto things.
2. I don't have to read or learn as much to get started. TL;DR FTW.
3. There are fewer surprises when my needs change or don't exactly follow the demo.
4. My bundle will be smaller or my ci build will be faster.
5. There's a good chance I could find/build another similar module to replace it if I needed to.

SOLUTION: Smaller is better, but if you have dependencies you need to use tools like:

• npm outdated
• greenkeeper
• next-updater and next-update
• snyk
• nsp

License

MIT. I rarely remember what the other licenses mean, so I usually do a quick read if it's not MIT. Before React changed it's license, I didn't trust it. Sometimes the suspicious license is in the dependencies so you have to run a "dep-check". A confusing or non-standard license could also cause friction so I chose MIT.

SOLUTION: Use a common, trusted, license and make sure github "sees" it.

Health

Modules can have technical debt. Lots of open issues, pull requests that have been open a long time, and a long TODO list are all signs of tech debt. Modules can also have velocity and potential velocity. We measure potential with metrics like contributors, forks, and stars. Actual velocity, requires releases (assuming there are pull requests or open issues).

Once you dig into the code or docs, you can find loads more reasons to trust (or not trust) a module:

• Does the project have tests?
• Does the project measure test coverage? If so, what percentage?
• Does the project have ci?
• If the project has dependencies, are they secure? Up to date?
• If it's a browser module, did someone test it in a real browser?
• Is there a defined code style?
• CONTRIBUTING: signals that it's ready for community involvement (I adapted the contributor covenant Code of Conduct).
• CHANGELOG and semver is a sign of forethought and organization

If you want a quick answer, look at repocheck. The algorithm isn't perfect, but it tends to focus on tech debt, which I appreciate.

For my module, I can't manufacture stars, contributors, or dependent projects (beyond my own). So, I concentrated on the things I could control like testing and a repeatable workflow. Personally, this was the best part. I actually love making updates because the release process is so simple! I guess what they say about love works for modules too--you have to love yourself first.

SOLUTION: use tools to make common tasks repeatable. Most of these tools have several competing options depending on your needs or code style. My stack includes:

• standard-version
• tape
• prettier
• eslint
• travis-ci
• nyc and coveralls.io

Then show your process off using badges. This gives developers a quick look at your module's development style and health.

Theoretical Use

Demos. The "try in your browser" feature of npm works for simple stuff but not for everything. That's when I want a glitch, codepen, fiddle, or downloadable demo. If the demo doesn't work, I can't trust this module.

"Code the documentation" is such a cool idea. I caught critical problems in my packages before release by pointing my documentation examples at the dist version of my code. Next, I need to work out more concrete examples (like a TODO app).

In version 0.14, I also learned to provide nice-looking API docs using documentation.js. By adding JSDoc comments to the code and changing my github settings to point to master/docs for gh-pages, I get a free documentation website. Nice! I think this will help invite others to contribute and help answer questions without issues.

SOLUTION:

• code the documentation using jsmd and run it every time you run tests.
• If it's large, make an examples folder and run those tests.
• Make sure your explanations are easy to read. I used several retext plugins from unified and they really helped!
• microbundle provides all the various output formats ❤️.
• Use tools like rimraf and cross-env so our Windows friends don't have a bad time at the terminal.
• documentation.js makes some sweet docs and encourages you to comment your code.

Actual Use

One of my favorite things to do when I get a new module is go to the module's github page. Then, click "Insights" > "Dependency graph" > "Dependents". I review who else is using this module in open source and sometimes I go look for how they used it. You can see how long a project has used the module. You can also see how the pull request went. I do a quick "search this repository" to find where they use the module and any tests that use it. That one trick has saved me hours of frustration.

SOLUTION: make a module developers can trust and talk about it.

TL;DR I made @set-state/core with love.

👍
❤️ ❤️ ❤️ ❤️ ❤️