Learn, design or document codebase by putting breadcrumbs in source code. Live updates, multi-language support and more.

Overview

npm version Open Source Love

What · Demo · Get started · Features · Case studies · Support

What

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 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.

Check out my talk at React-Finland for more details.

If you like this project, follow me on Twitter @bliashenko to hear about things I am building.

Demo

Check out the example of standalone version running here.

Get started

Install and run

Pre-condition: update/install NodeJS version to be >= 8.11.1

  1. Install codecrumbs globally (yarn global add codecrumbs)
  2. 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 .
  3. Go to http://localhost:2018 in the browser to check it out.

Configuration

Run codecrumbs with CLI params or specify static config file codecrumbs.config.js (see example here)

CLI Config file Description Example
d projectDir Relative path to project source code directory -d src
e entryPoint Relative path to project source entry point file (must be inside dir) -e src/app.js
x excludeDir Relative path(or paths separated by ,) to directories for exclusion -x src/doc,src/thirdparty
p clientPort Port for Codecrumbs client (optional, default 2018) -p 2019
n projectNameAlias Project name alias (optional, default same as -d value) -n my-hello-world
C - Path to codecrumbs.config.js (optional, by default will try to find the file in PWD) -C config/codecrumbs.config.js
D debugModeEnabled Enable debug mode for logs (optional, default is false) -D

Features

Breadcrumbs and trails

UI explained:

  • 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:[parameters;].

cc (stands for "CodeCrumb") is a prefix which used by the parser; check example of parameters in the table below:

Example Description Use case
//cc:remember place simple breadcrumb, remember place is a title of our first breadcrumb Mark an important place to not forget where it was
//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
//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.).
//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

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.

Multi-codebase integration

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 codecrumbs for directory you need.

Multi-language support

Current version supports next programming languages:

  • C#
  • C++
  • Fortran
  • Go
  • Haskell
  • Java
  • JavaScript
  • Kotlin
  • PHP
  • Python
  • Ruby
  • TypeScript

Please file an issue to support other language you would like to have.

Dependencies

Note: In current version only [JavaScript, TypeScript] offer this feature

UI explained:

  • 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”)

Flowchart

Note: In current version only JavaScript offers this feature

js2flowchart is used in the sidebar to draw flowchart for the selected file code.

Support

Any support is very much appreciated! 👍 😘 ❤️ If you like this project, please, put a and tweet about it. Thanks!

Please, consider making financial donation, 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 for discussion.

Sponsors

Development supported by 0+X

Backers

Contribute

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

WIP

Next features are developing:

  • VS Code extension - some neat features right inside the code editor. Checkout the repo here.
Comments
  • Error at getting repositorys

    Error at getting repositorys

    Looks like the path issue is fixed.

    but now it throws an error at the dependecies option:

    uncaught at reactByUpdatingFoldersState TypeError: Cannot read property 'dependencies' of undefined

    on Tree.js

    {dependenciesDiagramOn && selectedNode.dependencies && ( <DependenciesTree namespace={namespace}

    Originally posted by @Motytheultimate in https://github.com/Bogdan-Lyashenko/codecrumbs/issues/14#issuecomment-463325932

    opened by Motytheultimate 18
  • Corrupted Content Error

    Corrupted Content Error

    Firefox displays this content when attempting to run codecrumbs against a simple, working react project.

    Tested with 2 separate projects.

    Corrupted Content Error
    
    The site at http://localhost:2018/ has experienced a network protocol violation that cannot be repaired.
    
    The page you are trying to view cannot be shown because an error in the data transmission was detected.
    
        Please contact the website owners to inform them of this problem.
    
    

    I am not sure what additional information would be helpful. I also tried this in Opera. I am very interested in getting this working and any assistance will be appreciated.

    opened by suntzuisafterU 12
  • Wrong scroll position of code in Crumbs tab

    Wrong scroll position of code in Crumbs tab

    I just started using codecrumbs, and I'm finding that the crumb code listings are not automatically scrolled to the crumb, they are scrolled to a vertical offset that is significantly smaller than the crumb offset, so that the crumb line is not visible unless I scroll it into view. :(

    I peeked at the code, and the code for scrolling a crumb into view seems to hardcode a line height of 15. In practice, the line height is 18 (font size of 12px and line height of 1.5).

    opened by dgreensp 10
  • Multiple crumbs in the same file

    Multiple crumbs in the same file

    It seems that currently only one crumb per file is supported, however it would be incredibly useful if there was a way to do multiple crumbs.

    The particular use case I am thinking of is a file (like a reducer) that might be involved in more than one trail.

    PS Thanks for your work on this package, its a brilliant idea!

    opened by andrewmherren 10
  • Codecrumbs views don't finish loading

    Codecrumbs views don't finish loading

    My Codecrumbs browser is in a perpetual loading state. I've added some logging on my end and it seems to be parsing the //cc comments properly, so I can't figure out why there is no visualisation.

    Browser codecrumbs

    Debug parsed

    opened by adityavm 9
  • Error at path

    Error at path

    hi there seems to be an error in your sidebar.js and a few more. i tried it with running your project directly from your sources.

    the error i get is the follwing

    uncaught at reactOnSourceSet TypeError: Cannot read property 'path' of undefined On example is at the follwing

      <React.Fragment>
      <div>{file.path}</div>
      <div className={'copyIcon'}>
        <Copy copyText={file.path} />
      </div>
    </React.Fragment>
    

    in sidebar js https://github.com/Bogdan-Lyashenko/codecrumbs/blob/master/src/public/js/components/sideBar/component/SideBar.js

    opened by Motytheultimate 7
  • feat: added php dependencies support

    feat: added php dependencies support

    I added php dependency support. (but php namespace-use only)

    Also I changed behaver when checked for dependencies > direct only

    Could you review it.

    Feature change

    • enabled full-featres support for php
    • implemented parsing imported dependency and namespace dependency for php by php-parser
    • added src-php in example project
    • changed behaver of dependencies when checked for direct only
    opened by syarig 5
  • hot reload does not work correctly when using typescript

    hot reload does not work correctly when using typescript

    Whenever i save changes, codecrumbs still detect changes and recompile but the trail option on browser contain only current option, others are disappeared.

    opened by 6thpath 5
  • Multiple crumbs view is skewed

    Multiple crumbs view is skewed

    Hello, I'm playing with CC comments in my Go backend with lots of microservices, currently I'm trying to document a single flow of user authorization, that is split between different files. I'm using numbered code crumbs, but the view is getting skewed and not readable in the end, e.g.

    screenshot 2019-02-20 at 18 21 29

    I have multiple numbered CC's in the same file, so the view orders them not by the tailing order, but in the order of location in files. It think this is an issue, any suggestions how to avoid this?

    opened by xlab 5
  • codecrumbs: command not found

    codecrumbs: command not found

    Screenshot 2019-05-03 at 11 43 27

    Tried following the tips in issue #17 - but I still can not use the codecrumbs command. Also tried updating "ecstatic" but I get the same warning. Any ideas what's going on here?

    Edit: Noticed there's a typo in my screenshot. Also using command codecrumbs -d src -e src/index.js was not effective

    opened by pomfrida 4
  • Support Nodejs

    Support Nodejs

    Hi,

    This project looks really cool! Sorry if am being dumb or not looking for more info. But I can't seems to work this with my node-boilerplate. I added it as dependency and running it with this syntax.

    $ npx codecrumbs -d src -e index.js
    

    Environment

    • Node/NPM - 10.7/6.1
    • MACOS - Mojave(10.14.3)
    opened by joshuaalpuerto 4
  • Codecrumbs hasn't launched on Python project

    Codecrumbs hasn't launched on Python project

    internal/modules/cjs/loader.js:638
        throw err;
        ^
    
    Error: Cannot find module 'fs-readdir-recursive'
        at Function.Module._resolveFilename (internal/modules/cjs/loader.js:636:15)
        at Function.Module._load (internal/modules/cjs/loader.js:562:25)
        at Module.require (internal/modules/cjs/loader.js:692:17)
        at require (internal/modules/cjs/helpers.js:25:18)
        at Object.<anonymous> (/home/t.kohler/.config/yarn/global/node_modules/codecrumbs/src/server/code-parse/language/php/namespaces.js:1:26)
        at Module._compile (internal/modules/cjs/loader.js:778:30)
        at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
        at Module.load (internal/modules/cjs/loader.js:653:32)
        at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
        at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    

    Hi! Tried to launch the codecrumbs on the Python project and got this. May I ask for suggestions to fix this?

    opened by trkohler 5
  • How to configure codecrumbs to work with Typescript project?

    How to configure codecrumbs to work with Typescript project?

    I struggle to make codecrumbs working for Typescript project I working on. Any suggestion what should I do to be able to use codecrumbs for a project?

    opened by SuperManEver 4
  • Client can't connect to server in WSL environment

    Client can't connect to server in WSL environment

    Environment: Windows 10 with WSL2. codecrumbs installed in WSL2 OS.

    How to reproduce:

    • start codecrumbs in wsl console
    • open browser and go to localhost:2018 (in Windows) After that client just hanging out. Console contains the message: "WebSocket connection to 'ws://127.0.0.1:3018/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED".

    How to solve: It's need to just use localhost in url instead of 127.0.0.1. Otherwise ports from WSL are not accessible.

    opened by MaksimMyshkin 2
  • Added e2e test scripts as per #87

    Added e2e test scripts as per #87

    • [x] Added test:e2e script to package.json
    • [x] Added page-objects dir to tests/e2e/ and created a page-model. (In Progress)
    • [x] Added tests to cover some user-flows. (In Progress)
    opened by christyjacob4 0
  • codecrumbs with -i ide feature

    codecrumbs with -i ide feature

    Finally go to trying this out last Friday and the navigation in vscode using -i code didnt work.

    I notice today you have removed this '-i code' documenation in last few days.

    This is no longer a feature?

    opened by rluiten 8
Owner
Bohdan Liashenko
Fan of JS and high quality code (whatever that means). Follow me on twitter @bliashenko
Bohdan Liashenko
dexy 2.2 1.9 L4 Python is a free-form literate documentation tool for writing any kind of technical document incorporating code.

Dexy Dexy is open source automation software with features especially designed for documentation and reporting. More information at http://dexy.it Doc

null 304 Sep 30, 2022
Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system

Sphinx-Immaterial Theme This theme is an adaptation of the popular mkdocs-material theme for the Sphinx documentation tool. This theme is regularly ma

Jeremy Maitin-Shepard 89 Jan 4, 2023
JavaScript documentation generator for node using markdown and jsdoc

Dox Dox is a JavaScript documentation generator written with node. Dox no longer generates an opinionated structure or style for your docs, it simply

TJ Holowaychuk 2.1k Jan 7, 2023
Pointers to useful, well-written, and otherwise beautiful documentation.

DO YOU WANT TO BUILD AND WRITE GLORIOUS TECHNICAL DOCUMENTATION FULL TIME? EMAIL [email protected]. WE NEED YOU. Beautiful Docs I love documentation. If

Mark Phillips 7.9k Jan 4, 2023
Literate Programming can be Quick and Dirty.

____ /\ _`\ \ \ \/\ \ ___ ___ ___ ___ \ \ \ \ \ / __`\ /'___\ /'___\ / __`\ \ \ \_\ \ /\ \ \

Jeremy Ashkenas 3.5k Dec 31, 2022
null 147 Dec 8, 2022
iSphinx 2 Jun 24, 2022
freeCodeCamp.org's open source codebase and curriculum. Learn to code for free.

freeCodeCamp.org's open-source codebase and curriculum freeCodeCamp.org is a friendly community where you can learn to code for free. It is run by a d

freeCodeCamp.org 359.2k Jan 7, 2023
All terminal commands in one place (you can Contribute to it by putting latest commands and adding Readme)

Terminal-Commands All basic terminal commands in one place Show some ❤ by some repositories You can contribute to this readme If you to contribute wit

Shehzad Iqbal 7 Dec 15, 2022
A plugin for creating hierarchical navigation in Astro projects. Supports breadcrumbs too!

astro-navigation A plugin for creating hierarchical navigation in Astro projects. Supports breadcrumbs too! Full docs coming soon! Basic usage This pa

Tony Sullivan 7 Dec 19, 2022
whatsapp api to remote your whatsapp device. Support multi device, multi client. Still update to more feature. Please fork, star, donate and share.

Ndalu-wa-client DEPENDENCIES : { "@adiwajshing/baileys": "^4.2.0", "@adiwajshing/keyed-db": "^0.2.4", "axios": "^0.27.2", "body-parser

null 29 Jan 4, 2023
A refined tool for exploring open-source projects on GitHub with a file tree, rich Markdown and image previews, multi-pane multi-tab layouts and first-class support for Ink syntax highlighting.

Ink codebase browser, "Kin" ?? The Ink codebase browser is a tool to explore open-source code on GitHub, especially my side projects written in the In

Linus Lee 20 Oct 30, 2022
A framewok for building efficient and scalable, cross-platform bots (WhatsApp, Discord, Telegram and more) in a single codebase

project... An over-engineered all-in-one bot framewok for building efficient and scalable bots. Yep that's not a typo u heard it right "scalable bots"

Shubham Badgujar 6 Dec 24, 2022
A very lightweight and chatbot with multi language support

A very lightweight and chatbot with multi language support

Artificial Intelligence 6 Jul 25, 2022
Codú's open-source codebase. A space for coders.

Running the app $ npm install # development $ npm run dev Open http://localhost:3000 with your browser to see the result. You can start editing the p

Codú Community 18 Jan 2, 2023
🌸 A fast and fun way to learn Japanese alphabets: hiragana & katakana. Don't wait - learn now!

Sakurator | Start learning 日本語 here Sakurator (Website publish date: ~4-6 April '22) - a personal trainer for learning Japanese alphabets (hiragana &

Anatoly Frolov 3 Jun 22, 2022