{"id":19686333,"url":"https://github.com/closeio/best-practices-documentation","last_synced_at":"2026-03-11T12:11:40.992Z","repository":{"id":190624140,"uuid":"683081119","full_name":"closeio/best-practices-documentation","owner":"closeio","description":"This is a library and tool to help teams document their coding best practices","archived":false,"fork":false,"pushed_at":"2026-01-14T16:47:23.000Z","size":382,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-01-14T19:59:52.396Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/closeio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-08-25T14:52:05.000Z","updated_at":"2026-01-14T16:46:22.000Z","dependencies_parsed_at":"2023-08-25T16:46:21.482Z","dependency_job_id":"16cd2972-552a-4c58-98b1-ba064d9491cb","html_url":"https://github.com/closeio/best-practices-documentation","commit_stats":null,"previous_names":["closeio/best-practices-documentation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/closeio/best-practices-documentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/closeio%2Fbest-practices-documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/closeio%2Fbest-practices-documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/closeio%2Fbest-practices-documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/closeio%2Fbest-practices-documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/closeio","download_url":"https://codeload.github.com/closeio/best-practices-documentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/closeio%2Fbest-practices-documentation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30380935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T18:27:33.830Z","updated_at":"2026-03-11T12:11:40.946Z","avatar_url":"https://github.com/closeio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Close Best Practices Documentation\n\n`close-best-practices` is a library and a tool to help teams document their\ncoding best practices.\n\n(Interested in working on projects like this? [Close](https://www.close.com) is\nlooking for [great engineers](https://jobs.close.com) to join our team!)\n\n## Philosophy\n\nThis library is built to embody the following principles:\n\n1. Documentation should live as close to the code as possible (preferably in the\n   code)\n2. Documentation should be discoverable\n3. Documentation should update automatically when the associated code changes\n4. You shouldn't have to actually look at the code to read through our best\n   practices\n\n## Installation\n\nYou can install this package via npm:\n\n    npm i --save-dev @closeio/best-practices-documentation\n\n    yarn add -D @closeio/best-practices-documentation\n\n## Tagging your Code as a Best Practice\n\nYou can tag blocks of code as best practices with specially formatted comments:\n\n```tsx\n// @BestPractice React Components\n// @BestPractice.subtitle State Updates\n// @BestPractice.description\n//   If you need to update state based on the current value, use\n//   the functional version of the state setter rather than using\n//   the `value`. This keeps `useCallback` from creating a new function\n//   every time the value changes.\nconst [value, setValue] = useState(0);\nconst incrementValue = useCallback(\n  () =\u003e setValue((currentValue) =\u003e currentValue + 1),\n  [],\n);\n// @BestPractice.end\n```\n\nYou can also document values in JSX blocks with the `{/* ... */}` comment\nformat.\n\nCheck out the sample project that is part of the code to see more examples.\n\n### Limitations\n\n- We currently do not support multi-line comments.\n- This tool only looks at files with `.js`, `.jsx`, `.ts`, and `.tsx` extensions\n\n## Extracting Best Practices Documentation\n\nTo extract your best practices documentation, you can invoke our CLI tool:\n\n    npx best-practices write -s src/ -g docs/best-practices -u \"https://github.com/\u003cyour org\u003e/\u003cyour repo\u003e/tree/main\"\n\nThis will scan through your code in `src` and build best practices Markdown\nfiles from your tagged code. The contents of the `-g` directory will be\ncompletely overwritten, so make sure you point to a directory that doesn't\ncontain any manually written documentation.\n\nThis will also write out a `digest.txt` file that is used to track changes to\nyour generated documentation.\n\n## Checking Docs Freshness\n\nYou can check to see if your generated docs are out of date with your code with\nthe `check` subcommand:\n\n    npx best-practices check -s src/ -g docs/best-practices\n\nThis will gather your best practices documentation from your code and generate a\ndigest, and compare those to the digest that was written out the last time docs\nwere generated. The `check` command will exit with a status code of `1` if the\ndocs are out of date, making this a good command to use in a pre-commit hook or\na CI step.\n\n## Inserting Blocks Into Static Documentation\n\nIf you'd like to insert (and keep up-to-date) some best practices into static\ndocumentation, meaning docs that you type out yourself, and aren't completely\ncontrolled by this tool, you can do that with specially formatted comments and\nmeta tags.\n\n### In Your Code\n\nIn your code, add a `id` meta field to the documentation block:\n\n    // @BestPractice.id insertIntoStaticDocs\n\nThis id should be unique throughout your codebase, but this is not checked or\nenforced by the tool. If you have multiple best practice blocks with the same ID\nthen the last one picked up by the tool when parsing your code will be used.\n\n### In Static Documentation\n\nIn your static markdown documentation file, add a comment like this where you'd\nlike to insert a best practice:\n\n    \u003c!-- @BestPractice.insert insertIntoStaticDocs --\u003e\n    \u003c!-- @BestPractice.end --\u003e\n\nIf your file is a `.mdx` Markdown file, use `JSX` style comments instead:\n\n    {/* @BestPractice.insert insertIntoStaticDocs */}\n    {/* @BestPractice.end */}\n\nIt's important to have both the start and end lines, as these will be used as\nboundaries of the program to know where to replace the code.\n\n### From the Command Line\n\nIn order to write out to static docs, you'll have to point the tool at your docs\nroot with the `-d` command line argument.\n\nE.g.\n\n    `npx best-practices write -s src/ -g docs/best-practices -d docs/ ...`\n\n### Used IDs\n\nIf a best practice is inserted into static documentation, it will not be\ninserted into the generated docs. It will however still be included in the\ndigest for checking doc freshness.\n\n## Keeping Docs Up-to-date\n\nThere are several strategies for keeping your docs up-to-date:\n\n1. Create a pre-commit hook that will run `best-practices write`\n2. Create a pre-commit hook that will run `best-practices check`\n3. Create a CI step that will run `best-practices check`\n4. If you have a documentation system that automatically creates a static\n   documentation site from your docs, you may be able to hook in the\n   `best-practices` command as part of that.\n\n## Customizing Docs Generation\n\nIf the default usage of the CLI tools doesn't fit your needs, you can use the\nlibrary to customize your best practice generation. We export all the primary\nutility functions that the `write` and `check` CLI subcommands use, and you can\ncompose those as you need\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloseio%2Fbest-practices-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloseio%2Fbest-practices-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloseio%2Fbest-practices-documentation/lists"}