Excellent newcomer setup: clear, well-documented, batteries-included, and genuinely low friction to contributing.
last scored 2026-06-15
Readiness lenses
The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.
How ready the repo is for an AI coding agent to read, build, and operate it.
22 of 34 checks passed across 6 categories.
Machine Orientation
4 checks passed3 problems found
- mediumAgent instructions file
AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
Fix: Add an AGENTS.md naming the entry points, the build/test commands, and the house conventions.
- lowllms.txt present
An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.
Fix: Add an llms.txt pointing at the key docs and entry points.
- lowArchitecture doc
An ARCHITECTURE doc hands an agent the module map instead of making it infer one.
Fix: Add an ARCHITECTURE.md describing the major components and how they fit.
- README present — An agent reconstructs what the repo is and how to work in it from the README first.
- Repository description set — The one-line description is the fastest orientation signal an agent reads.
- Topics set — GitHub topics situate the repo's domain and stack for an agent at a glance.
- Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.
Reproducible Setup
3 checks passed3 problems found
- mediumContainer or dev-container
A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
Fix: Add a Dockerfile, a compose file, or a .devcontainer so the environment is declared, not assumed.
- lowEnv template present
A .env.example tells an agent which configuration keys it must supply to run.
Fix: Ship a .env.example listing every required key with placeholder values.
- lowDev container
A .devcontainer gives an agent a one-command, fully-declared environment.
Fix: Add a .devcontainer so the toolchain is declared, not assumed.
- Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
- Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
- Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
Code Navigability
2 checks passed0 problems found
- Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
- TypeScript strict mode on — Strict typing gives an agent typed signatures to anchor an edit on, not guesses.
Verification Surface
5 checks passed2 problems found
- lowTask runner present
A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.
Fix: Add a Makefile / Taskfile / justfile collecting the common commands.
- lowTypecheck command
A typecheck script lets an agent catch type errors before they ship.
Fix: Add a `typecheck` script (e.g. `tsc --noEmit`).
- Tests present — Runnable tests are the ground truth an agent checks its own edits against.
- Test command defined — A `test` script is the documented, discoverable way to run the suite.
- Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
- CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
- Build command — A documented build command is the discoverable way for an agent to produce artifacts.
Agent Safety
5 checks passed3 problems found
- medium.gitignore covers env files
An ignore rule for .env is what keeps the next careless commit from leaking secrets.
Fix: Add `.env` (and `.env.*`) to .gitignore.
- mediumSecurity policy
A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.
Fix: Add a SECURITY.md stating the disclosure channel and the repo's security rules.
- lowCODEOWNERS present
CODEOWNERS marks the 'don't touch without review' zones an agent should respect.
Fix: Add a CODEOWNERS file marking the sensitive paths.
- No committed .env — A tracked real .env hands secrets to anything — including an agent — that reads the repo.
- No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
- Automated dependency updates — Dependabot / Renovate keeps dependencies patched without a human in the loop.
- .gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
- License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.
Context Economy
3 checks passed1 problem found
- lowGenerated / vendored files marked
A .gitattributes linguist marker tells tools (and agents) what to skip.
Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).
- Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
- Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
- No oversized source file — A single file in the hundreds of KB blows past an agent's effective context window.
How ready the repo is for a human newcomer to understand, set up, and contribute.
90 / 10017 of 25 checks passed across 6 categories.
First Impression
95Immediate clarity on purpose, scope, and maturity; attractive branding and rich ecosystem context.
The README opens with the bear mascot, concise headline (state management for React), and immediately demonstrates install, basic usage, and comparisons to alternatives (Redux, Context API). The intro paragraph signals seniousness: explicit acknowledgment of solved hard problems (zombie child, React concurrency, context loss) with links to proof. 58k+ stars, active CI badges, live demo link, and extensive docs site signal maturity and care without overselling.
Getting Running
92Copy-paste install works; pnpm lock file + script-driven build; dev setup clearly documented.
README shows `npm install zustand` prominently. The CONTRIBUTING.md spells out the full dev flow: `pnpm install`, fork, branch, build with `pnpm run build` (or watch mode), test with `pnpm run test`, and even includes advanced testing via CodeSandbox CI. pnpm-lock.yaml is present, preventing 'works on my machine' surprises. The test suite (vitest, TypeScript types, linting) runs via explicit scripts (`test:spec`, `test:types`, `test:lint`). Rollup config is complex but documented in scripts.
Finding Your Way
88Well-organized source tree, clear entry points (vanilla, react, middleware), but architecture overview is implicit rather than explicit.
The `src/` structure is clean: `vanilla.ts`, `react.ts`, `middleware.ts`, and a `middleware/` folder with named exports (immer, persist, redux, devtools, etc.). File tree and examples make the module boundaries obvious. However, the README doesn't include a 'Project Structure' or 'Architecture' section explaining which file does what or how the middleware system plugs in—a newcomer would need to infer this from code or docs site.
Path to Contribute
94Detailed CONTRIBUTING.md with full dev workflow, issue templates, PR template, and commit conventions.
CONTRIBUTING.md walks through forking, branching, testing, building, and even linking locally or via CodeSandbox CI. It covers conventional commits (feat, fix, refactor, chore, docs, test) with examples and scope guidance. GitHub issue templates (bug_report.md, discussion config) and pull_request_template.md are in place. Issues are few (4 open), and discussions are routed correctly (bugs → discussions, not issues). No CLAs or legal blockers mentioned.
Signs of Life
92Recent push (June 2026 in the snapshot), active CI pipelines, solid contributor base, low issue backlog.
Last commit is 2026-06-15 (very recent). Multiple GitHub Actions workflows (test, publish, docs, preview-release, compressed-size, test-multiple-builds/versions, test-old-typescript) indicate ongoing CI/CD and maintenance discipline. The FUNDING.json and sponsor banner suggest sponsored sustainability. Only 4 open issues despite 58k+ stars indicates either excellent triage or active closure. Contributor list (Paul Henschel, Jeremy Holcomb, Daishi Kato) is visible.
Open Door
93MIT license clearly stated, active Discord community link, no code of conduct visible but community is welcoming.
LICENSE file present and confirmed MIT in package.json. README includes Discord shield linking to the Poimandres community (740k+ members). CONTRIBUTING.md directs bug reports and feature discussions to GitHub discussions, creating a low-friction path for first-timers. However, there is no explicit CODE_OF_CONDUCT.md or SECURITY.md policy visible in the file tree, which is a minor gap for a 58k-star project expecting global contributors.
First Impression
3 checks passed0 problems found
- README present — The README is the first screen — with none, a newcomer has nothing to land on.
- Repository description set — The one-line description sets expectations before a newcomer even opens the README.
- Topics set — Topics situate the project's domain at a glance and help a newcomer find it.
Getting Running
3 checks passed3 problems found
- mediumOne-command environment
A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
Fix: Add a Dockerfile, a compose file, or a .devcontainer for a one-command setup.
- lowEnv template present
A .env.example shows a newcomer exactly which settings they must fill in to run it.
Fix: Ship a .env.example listing every required key with placeholder values.
- lowOne-click dev container
A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.
Fix: Add a .devcontainer for a one-click, batteries-included environment.
- Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
- Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
- Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
Finding Your Way
2 checks passed1 problem found
- mediumArchitecture / overview doc
An overview hands a newcomer the map instead of making them reconstruct it.
Fix: Add an ARCHITECTURE.md (or a 'Project layout' README section) naming the key directories.
- Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
- No oversized source file — A single thousand-line file is a wall a newcomer bounces off.
Path to Contribute
4 checks passed2 problems found
- lowPull-request template
A PR template tells a first-time contributor what a good change includes.
Fix: Add a PULL_REQUEST_TEMPLATE.md.
- lowTask runner
A Makefile / Taskfile gives a contributor a single index of the project's commands.
Fix: Add a Makefile / Taskfile collecting the common dev commands.
- CONTRIBUTING guide — A CONTRIBUTING guide is the difference between a guessed and a guided first PR.
- Issue templates — Issue templates show a newcomer how to file something useful — and that contributions are welcome.
- Test command defined — A documented test command lets a contributor check their change before opening a PR.
- Lint command — A linter lets a first-time contributor catch style issues before review.
Signs of Life
3 checks passed0 problems found
- Tests present — A test suite signals a project that's cared for, not abandoned.
- CI configured — Green CI on every change tells a newcomer the project is actively kept working.
- Automated dependency updates — Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.
Open Door
2 checks passed2 problems found
- lowCode of conduct
A code of conduct states the social ground rules that make it safe to step in.
Fix: Add a CODE_OF_CONDUCT.md (the Contributor Covenant is the de-facto standard).
- lowSecurity policy
A SECURITY.md tells a newcomer how to report a problem responsibly.
Fix: Add a SECURITY.md describing how to report a vulnerability.
- License present — With no license the project isn't legally reusable — the door is shut however friendly the README.
- License is a standard one — A non-standard or custom license is a legal question mark a newcomer won't resolve.
Where the grip slips
- lowFinding Your Way+6 pts if fixed
No architecture overview or project structure guide in README
While the README is excellent for quick onboarding to *using* Zustand, it doesn't explain the *internal* organization: how vanilla, React, and middleware layers relate, which file does what, or how to navigate the codebase to make a contribution. A newcomer wanting to fix a bug in the persist middleware would need to infer the structure from exploration or the docs site.
Fix: Add a 'Project Structure' or 'Architecture' section to the README (3–4 short paragraphs) or link to a ARCHITECTURE.md file that explains: vanilla core → react wrapper, middleware system, build output (CJS, ESM, types), and where tests live.
- lowOpen Door+5 pts if fixed
No CODE_OF_CONDUCT.md in repository root
A 58k-star project with global contributors should have an explicit code of conduct to set expectations for community behavior and establish safe reporting channels. Its absence, while not a legal barrier, leaves newcomers unsure of the project's values and what happens if they witness or experience conflict.
Fix: Add a CODE_OF_CONDUCT.md to the repository root (e.g., Contributor Covenant v2.1) and link it prominently in CONTRIBUTING.md and/or README.
- lowPath To Contribute+4 pts if fixed
No beginner-labeled issues or 'good first issue' tracking
With only 4 open issues visible and no mention of 'good-first-issue' or 'help-wanted' labels in the issue templates or CONTRIBUTING.md, a newcomer wanting to make a first contribution would struggle to find an approachable task. High-volume projects need explicit guidance to surface low-friction entry points.
Fix: Set up GitHub issue labels (good-first-issue, help-wanted, beginner-friendly) and retroactively tag a few existing issues or create starter tasks. Mention this in CONTRIBUTING.md: 'Look for issues tagged good-first-issue if you're new.'
- lowPath To Contribute+3 pts if fixed
CONTRIBUTING.md references external pmndrs/docs repo but doesn't make docs contribution optional
The docs setup requires cloning a separate pmndrs/docs repository and configuring environment variables to test docs locally. This is a high-friction extra step for a first-time contributor who just wants to fix code or add a unit test. It may discourage docs-only or code-only PRs.
Fix: Clarify in CONTRIBUTING.md: 'To contribute docs, see [Docs Setup]. To contribute code or tests, you can skip this step.' Restructure the docs section to be optional and clearly marked as a separate workflow.
Show your score
[](https://latch.fyi/pmndrs/zustand)Share this analysis
https://latch.fyi/pmndrs/zustandFixed some issues? Re-analyze to measure your progress →
Copy the whole report
Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.