{"id":15029449,"url":"https://github.com/bogdan-lyashenko/codecrumbs","last_synced_at":"2025-05-14T19:07:45.989Z","repository":{"id":41983577,"uuid":"131726361","full_name":"Bogdan-Lyashenko/codecrumbs","owner":"Bogdan-Lyashenko","description":"Learn, design or document codebase by putting breadcrumbs in source code. Live updates, multi-language support and more.","archived":false,"fork":false,"pushed_at":"2021-09-11T11:27:58.000Z","size":35178,"stargazers_count":2719,"open_issues_count":30,"forks_count":104,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-05-10T18:27:58.929Z","etag":null,"topics":["code","cpp","documentation-tool","java","javascript","learning","php","python","software-architecture","typescript"],"latest_commit_sha":null,"homepage":"https://codecrumbs.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bogdan-Lyashenko.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}},"created_at":"2018-05-01T15:00:36.000Z","updated_at":"2025-04-27T10:18:13.000Z","dependencies_parsed_at":"2022-09-04T02:11:43.612Z","dependency_job_id":null,"html_url":"https://github.com/Bogdan-Lyashenko/codecrumbs","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bogdan-Lyashenko%2Fcodecrumbs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bogdan-Lyashenko%2Fcodecrumbs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bogdan-Lyashenko%2Fcodecrumbs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bogdan-Lyashenko%2Fcodecrumbs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bogdan-Lyashenko","download_url":"https://codeload.github.com/Bogdan-Lyashenko/codecrumbs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["code","cpp","documentation-tool","java","javascript","learning","php","python","software-architecture","typescript"],"created_at":"2024-09-24T20:10:42.005Z","updated_at":"2025-05-14T19:07:44.656Z","avatar_url":"https://github.com/Bogdan-Lyashenko.png","language":"JavaScript","readme":" [![npm version](https://badge.fury.io/js/codecrumbs.svg)](https://badge.fury.io/js/codecrumbs) [![Open Source Love](https://badges.frapsoft.com/os/v2/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/) [\u003cimg src=\"https://img.shields.io/twitter/follow/bliashenko.svg?label=Stay%20Tuned\u0026style=social\"\u003e](https://twitter.com/bliashenko)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"/docs/logo-sm.png\" width=\"250\"/\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\n  \u003ca href=\"#what\"\u003eWhat\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n  \u003ca href=\"#demo\"\u003eDemo\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n  \u003ca href=\"#get-started\"\u003eGet started\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n  \u003ca href=\"#case-studies\"\u003eCase studies\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n  \u003ca href=\"#support\"\u003eSupport\u003c/a\u003e\n\u003c/h3\u003e\n\n**Have you ever got lost in a big or unknown codebase?** This tool will help you to solve that. Also, it will increase your development speed and give more knowledge about your application architecture.\n\u003e If you like this project, follow me on Twitter [@bliashenko](https://twitter.com/bliashenko) to hear about things I am building. \n\n## Codecrumbs v2\nCheck out new version of this project as [standalone application](https://codecrumbs.io). Just in a few clicks you can start exploring a codebase in more efficient way, create interactive visual guides and share them with others on your own blog! See [quick guide here](https://codecrumbs.io/guides/web-app-with-github/).\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://codecrumbs.io\" target=\"_blank\"\u003e\n   \u003cimg src=\"https://codecrumbs.io/external/img/common/app-ui-1.png\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\n## Demo\nCheck out prepared example for [**standalone version running here**](https://codecrumbs.io/app).\n\n## Codecrumbs v1\n\n\u003e**How it works?** You run `codecrumbs` command for a codebase, it analyzes source code and builds its visual representation. Write down a codecrumb-comment and codebase state will be reflected by visual client in browser on the fly.\n\u003e\n\u003e Check out [my talk at React-Finland](https://www.youtube.com/watch?v=S_1-1jzLxm4) for more details.\n\n\n\u003cimg src=\"/docs/main-ui-3.png\" width=\"100%\"/\u003e\n\n## Get started\n### Install and run\n\u003ePre-condition: update/install `NodeJS` version to be \u003e= *8.11.1*\n\n1) Install ```codecrumbs``` globally (```yarn global add codecrumbs```)\n2) Run ```codecrumbs -d project-src-dir -e project-src-dir/index.js```. Change parameters to match your project:```-d``` is *directory with source code*, ```-e``` is *entry point file* .\n3) Go to [http://localhost:2018](http://localhost:2018/#) in the browser to check it out.\n\n### Configuration\nRun codecrumbs with CLI params or specify static config file `codecrumbs.config.js` (see example [here](/example-project/codecrumbs.config.js))\n\nCLI | Config file | Description | Example\n--- | --- | --- | ---\n```d``` | ```projectDir``` | Relative path to project source code directory | ```-d src```\n```e``` | ```entryPoint``` | Relative path to project source entry point file (must be inside ```dir```) | ```-e src/app.js```\n```x``` | ```excludeDir``` | Relative path(or paths separated by ```,```) to directories for exclusion | ```-x src/doc,src/thirdparty```\n```p``` | ```clientPort``` | Port for Codecrumbs client (optional, default *2018*) | ```-p 2019```\n```n``` | ```projectNameAlias``` | Project name alias (optional, default same as ```-d``` value) | ```-n my-hello-world```\n```C``` | - | Path to codecrumbs.config.js (optional, by default will try to find the file in PWD) | ```-C config/codecrumbs.config.js```\n```D``` | ```debugModeEnabled``` | Enable debug mode for logs (optional, default is ```false```) | ```-D```\n\n## Features\n### Breadcrumbs and trails\n\n\u003cimg src=\"/docs/cc-ui-3.png\" width=\"750\"/\u003e\n\nUI explained:\n- enable \"Codecrumbs\" switch to have codecrumbs tree on the scheme (drop-down contains extra configuration)\n- choose \"current\" codecrumbs trail to display (can be either trail or all other \"simple\" codecrumbs)\n- select connection between two steps (code for two codecrumbs will be opened in \"Sidebar\" under \"Crumbs\" tab)\n- set other options in dropdowns to configure behaviour of the diagram (show code blocks, details, etc.)\n\n**How to get there?**\n\nLeave breadcrumb in code by writing down a comment: ```//cc:[parameters;]```.\n\n```cc``` (stands for \"CodeCrumb\") is a prefix which used by the parser; check example of parameters in the table below:\n\nExample | Description | Use case\n--- | --- | ---\n```//cc:remember place``` | simple breadcrumb, ```remember place``` is a title of our first breadcrumb | Mark an important place to not forget where it was\n```//cc:here is bug;well, seems like a bug in logic``` | simple breadcrumb, ```well, seems like a bug in logic``` is details for breadcrumb, separated by ```;``` | Add extra information, will be rendered in popups\n```//cc:signin#3;enable route``` | trail of breadcrumbs,```signin``` is the **trail ID**, ```#3``` is order **number of step**, ```enable route``` is a title describing the step. | A sequence of codecrumbs, use to describe some data flow (e.g. user login, or form submit, etc.).\n```//cc:signin#1;firebase sign in;+2;do call to firebase with credentials``` | trail of breadcrumbs,```+2``` is number of lines to highlight, separated by ```;``` | Use number of lines to highlight the code related to breadcrumb\n\n\u003e Note: current version supports single line comments only.\n\n\u003e Hint: you can use trail id without step number (e.g. ```//cc:groupname#;test```) just to group breadcrumbs, you always can add step numbers later when you know the correct order. \n\n### Multi-codebase integration\nYou might be interested to study connections between several codebases (sub-modules), codecrumbs supports that.\nSimply start codecrumbs multiple times (once for each codebase), it all **will be synced in one picture** inside the browser tab. To control a diagram UI - select it by clicking on it.\n\nE.g. for client-server application, go to the source directory for your server code and run `codecrumbs -e your-server-src/index.py -d your-server-src`, same for client `codecrumbs -e src-client/index.js -d src-client`.\n\u003e **Note:** codebases can be located wherever you want (**no** need to have them like mono-repo, etc.), simply run `codecrumbs` for directory you need.\n\n\u003cimg src=\"/docs/multi-codebase-cc-2.png\" width=\"100%\"/\u003e\n\n### Multi-language support\nCurrent version supports next programming languages:\n- `C#`\n- `C++`\n- `Fortran`\n- `Go`\n- `Haskell`\n- `Java`\n- `JavaScript`\n- `Kotlin`\n- `PHP`\n- `Python`\n- `Ruby`\n- `TypeScript`\n\nPlease file an issue to support other language you would like to have.\n\n### Dependencies\n\u003e Note: In current version only [JavaScript, TypeScript] offer this feature\n\n\u003cimg src=\"/docs/dep-ui-2.png\" width=\"100%\"/\u003e\n\nUI explained:\n\n- enable \"Dependencies\" switch\n- select connection between modules (all involved files will be opened in \"Sidebar\", so you can see “what is imported” and “its implementation”)\n\n### Flowchart\n\u003e Note: In current version only JavaScript offers this feature\n\n\u003cimg src=\"/docs/flow-ui.png\" width=\"100%\"/\u003e\n\n[js2flowchart](https://github.com/Bogdan-Lyashenko/js-code-to-svg-flowchart) is used in the sidebar to draw flowchart for the selected file code.\n\n## Support\nAny support is very much appreciated! 👍 😘 ❤️\nIf you like this project, please, **put a :star: and tweet about it**. Thanks!\n\nPlease, consider [making financial donation](https://opencollective.com/codecrumbs), it will help further development of more cool features! We'll thank you by including your name/company logo here ☺️. Feel free to [ping me](https://www.linkedin.com/in/bohdan-liashenko-bb365854/) for discussion.\n\n\u003ca href=\"https://opencollective.com/codecrumbs/donate\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://opencollective.com/codecrumbs/donate/button@2x.png?color=blue\" width=300 /\u003e\n\u003c/a\u003e\n\n#### Sponsors\nDevelopment supported by [0+X](https://0x.se)\n\n\u003ca href=\"https://0x.se\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://avatars0.githubusercontent.com/u/16350669?s=200\u0026v=4\" width=100 /\u003e\n\u003c/a\u003e\n\n#### Backers\n\u003ca href=\"https://opencollective.com/codecrumbs/backer/0/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/codecrumbs/backer/0/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/codecrumbs/backer/1/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/codecrumbs/backer/1/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/codecrumbs/sponsor/0/website\" target=\"_blank\"\u003e\u003cimg src=\"https://opencollective.com/codecrumbs/sponsor/0/avatar.svg\"\u003e\u003c/a\u003e\n\n## Contribute\nWhen contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the [owner](https://github.com/Bogdan-Lyashenko/) of this repository before making a change. Ideas and suggestions are welcome.\nTo start development environment, clone the repo \u0026 run:\n```javascript\nyarn \u0026\u0026 yarn start\n```\n\n## WIP\nNext features are developing:\n- **VS Code extension** - some neat features right inside the code editor. Checkout [the repo here](https://github.com/Bogdan-Lyashenko/vs-code-codecrumbs).\n","funding_links":["https://opencollective.com/codecrumbs","https://opencollective.com/codecrumbs/donate","https://opencollective.com/codecrumbs/backer/0/website","https://opencollective.com/codecrumbs/backer/1/website"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbogdan-lyashenko%2Fcodecrumbs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbogdan-lyashenko%2Fcodecrumbs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbogdan-lyashenko%2Fcodecrumbs/lists"}