Learn, design or document codebase by putting breadcrumbs in source code. Live updates, multi-language support and more.
|size (curr.)||35163 kB|
|license||BSD 3-Clause “New” or “Revised” License|
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.
How it works? You run
codecrumbscommand 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.
Check out my talk at React-Finland for more details.
Check out the example of standalone version running here.
Install and run
NodeJSversion to be >= 8.11.1
yarn global add codecrumbs)
codecrumbs -d project-src-dir -e project-src-dir/index.js. Change parameters to match your project:
-dis directory with source code,
-eis entry point file .
- Go to http://localhost:2018 in the browser to check it out.
Run codecrumbs with CLI params or specify static config file
codecrumbs.config.js (see example here)
||Relative path to project source code directory||
||Relative path to project source entry point file (must be inside
||Relative path(or paths separated by
||Port for Codecrumbs client (optional, default 2018)||
||Project name alias (optional, default same as
||-||Path to codecrumbs.config.js (optional, by default will try to find the file in PWD)||
||Enable debug mode for logs (optional, default is
Breadcrumbs and trails
- enable “Codecrumbs” switch to have codecrumbs tree on the scheme (drop-down contains extra configuration)
- choose “current” codecrumbs trail to display (can be either trail or all other “simple” codecrumbs)
- select connection between two steps (code for two codecrumbs will be opened in “Sidebar” under “Crumbs” tab)
- set other options in dropdowns to configure behaviour of the diagram (show code blocks, details, etc.)
How to get there?
Leave breadcrumb in code by writing down a comment:
cc (stands for “CodeCrumb”) is a prefix which used by the parser; check example of parameters in the table below:
||Mark an important place to not forget where it was|
||Add extra information, will be rendered in popups|
||trail of breadcrumbs,
||A sequence of codecrumbs, use to describe some data flow (e.g. user login, or form submit, etc.).|
||trail of breadcrumbs,
||Use number of lines to highlight the code related to breadcrumb|
Note: current version supports single line comments only.
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.
You might be interested to study connections between several codebases (sub-modules), codecrumbs supports that. Simply 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.
E.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.
Note: codebases can be located wherever you want (no need to have them like mono-repo, etc.), simply run
codecrumbsfor directory you need.
Current version supports next programming languages:
Please file an issue to support other language you would like to have.
- enable “Dependencies” switch
- select connection between modules (all involved files will be opened in “Sidebar”, so you can see “what is imported” and “its implementation”)
js2flowchart is used in the sidebar to draw flowchart for the selected file code.
Any support is very much appreciated! 👍 😘 ❤️ If you like this project, please, put a :star: and tweet about it. Thanks!
Development supported by 0+X
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owner of this repository before making a change. Ideas and suggestions are welcome. To start development environment, clone the repo & run:
yarn && yarn start
Next features are developing:
- VS Code extension - some neat features right inside the code editor. Checkout the repo here.