react-cosmos: the release check rewrites your entry points

The readme is three links

The whole page is a badge row, a getting-started section with a callout pointing at one integration for a newer rendering model, a community section with two destinations and a code of conduct, a contributing line, a sponsorship line, and a demo link.

Consequence: there is no install command, no example and no statement of what the thing does beyond the badge alt text. Everything a newcomer needs is on a documentation site, so the repository's front page cannot answer what it is. That is a deliberate choice for a project whose documentation lives elsewhere, and it does mean the first thing anyone landing here does is leave.

The release check rewrites the entry points twice

The scripts include one that runs a small program to link the entry points, and two named variants for pointing them at source and at the built output. The release check chains six of them:

    "release:check": "npm run build:clear && npm run build && npm run src && npm run lint && npm run dist && npm run test:run",

Consequence: the check both validates and mutates, and it ends with the manifests pointing at the built output rather than where they started. Every script in the chain is driven through a TypeScript runner rather than a compiled binary, so the build depends on being able to execute TypeScript directly. For a release process that is a normal arrangement; for a contributor who runs it and then looks at their working tree, it is a surprise.

Two task runners declare the same workspaces

The manifest declares two workspace globs, one over the packages and one over the examples:

"packages/*",
"examples/*"

and the repository also carries a configuration file for a different release tool, which is what the release and pre-release publish commands invoke.

Consequence: two mechanisms describe the same set of packages, and because the example glob is inside the workspace list, every example is an installed workspace and a publish tool that scans workspaces will see them too. That is a common combination and it is one more place where a new package has to be described twice.

Every development dependency is pinned to an exact version

The development dependency list is long and none of its entries uses a range: the browser test runner, the retry helper, both testing-library packages, every type definition package, the coverage provider, and the build loaders are all written with an exact version.

Consequence: the toolchain cannot move without an explicit edit, which is excellent for a repository whose builds have to be reproducible and means every security update in the test tooling is a deliberate commit across the whole tree. It also means a stale dependency sits there until somebody notices, because nothing in the pipeline will suggest otherwise.

The formatter and the linter are new-generation tools

Formatting and linting are each one command against a dedicated tool, and the root holds a configuration file for each. Type checking is a third command that runs the compiler directly.

Consequence: the project has committed to two tools written in a systems language, and anyone bringing an editor integration is bringing extensions for tools most editors do not know about. The saving is speed and a smaller dependency tree; the cost is that the usual editor affordances are missing until you install them. The type check also has no watch-mode script, unlike the tests.

There is a directory of planning documents in the tree

Alongside the source, the tests, the documentation and the examples, the top level holds a directory that is neither of those, plus two files naming coding assistants and two configuration directories for them.

Consequence: how the project intends to change is versioned next to what it currently does. That is either good practice or clutter depending on who is reading, and it is not separated from the code by anything other than a directory name. For a repository whose readme defers to a documentation site, the tree is where all the context actually lives.

The sponsorship link names one person

The contributing section points at a contributing document and then at a sponsorship link, and the sponsorship link goes to one individual's sponsor page.

Consequence: it tells you who a decision about the project's direction would come to, which is useful information for anyone depending on it. It is also the only place in a hundred-and-thirty-word readme that says anything about the human behind the tool.

The examples cover three bundlers and one shared package

The example directory holds three projects, one per bundler, plus a shared one that they presumably import.

Consequence: the integration surface is demonstrated three ways, which is the fastest way to see whether the tool fits your setup. A team on a fourth bundler has no example, and that is exactly where the documentation's per-integration guides take over. It also means every example is an installed workspace, so the cost of running the project's install includes all three.

Editorial conclusion

react-cosmos fits a component library team that wants a place to develop and test pieces in isolation rather than inside an application, and that already runs a browser test suite. It does not fit someone evaluating from the repository alone, because the front page will not tell you what it is or how to install it. It also does not fit a contributor who expects the release check to be read-only. Before adopting it, read the getting-started guide rather than the readme, and if you plan to release, run the release check in a clean tree because it leaves the entry points pointing somewhere different from where they started.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. react-cosmos/react-cosmos on GitHub
4. README
5. Releases