Skip to main content

RepositoryExplorer

RepositoryExplorer is an interactive repository map for your documentation. You describe your project's folder and file structure as data, and the component renders a VS Code-style solution explorer tree, a detail panel for the selected node, and an optional relation graph showing how files connect to each other.

It's great for onboarding — instead of asking new contributors to clone the repo and dig around, you hand them a navigable map with descriptions and relationships already filled in.

Live demo​

Loading demo…

Click on any node in the tree to see its description in the detail panel on the right. Nodes with relations show a small relation graph below the description.

Installation​

npm install docucraft

Usage​

Single tree with root​

For small, single-root repositories:

import { RepositoryExplorer } from 'docucraft';

<RepositoryExplorer
  initialExpandedDepth={2}
  root={{
    name: 'my-project',
    type: 'folder',
    path: 'my-project/',
    shortDescription: 'Project root.',
    children: [
      {
        name: 'src',
        type: 'folder',
        kind: 'folder',
        path: 'my-project/src/',
        shortDescription: 'Source code.',
        children: [
          {
            name: 'index.ts',
            type: 'file',
            kind: 'code',
            path: 'my-project/src/index.ts',
            shortDescription: 'Entry point.',
          },
        ],
      },
    ],
  }}
/>

Multiple sections with sections​

For larger repositories with multiple top-level concerns — monorepos, solutions with separate frontend and backend, etc.:

import { RepositoryExplorer } from 'docucraft';

<RepositoryExplorer
  sections={[
    {
      title: 'Backend',
      description: 'ASP.NET Core API',
      root: backendRoot,
    },
    {
      title: 'Frontend',
      description: 'React SPA',
      root: frontendRoot,
    },
  ]}
/>

Node kinds and icons​

The kind property controls the icon displayed next to each node. The following kinds are available:

folder, file, interface, implementation, code, dto, json, xml, yaml, text, markdown, image, video, audio, config, source, dependency, test, asset, docs, script, package, project, solution, lock, database, archive

When kind is not set, the icon falls back to a generic file or folder icon based on type.

Best practices​

Write shortDescription for every node. It's what readers see in the detail panel header — keep it one line, like a good git commit message.

Use longDescription for context that matters. Save it for nodes that need explanation beyond the obvious. Not every file needs a paragraph.

Add relations where it helps. Relations between nodes add a small graph to the detail panel. Use them for non-obvious links — "this service publishes to that queue", "this config file controls that process". Don't add relations just to add them.

Set defaultExpanded: true on the root node. Without it, the root starts collapsed and readers have to click to expand it before they see anything. A little pre-expansion makes the component feel more welcoming.

Use sections for multi-root repositories. If your project has more than one top-level directory that deserves explanation, sections gives each one its own header and lets readers navigate between them cleanly.

Props​

PropTypeDefaultDescription
rootRepositoryNode—Single root tree. Use for simple repositories.
sectionsRepositorySection[]—Multiple named sections. Use for larger repositories.
initialExpandedDepthnumber1How many levels are expanded on first render.
showSectionDescriptionsbooleantrueShow item counts and section tooltips.
labelsPartial<RepositoryExplorerLabels>—Override UI strings for localization.

Provide either root or sections, not both.

RepositoryNode​

type RepositoryNode = {
  id?: string;
  name: string;
  type: 'folder' | 'file';
  kind?: RepositoryNodeKind;
  shortDescription: string;
  longDescription?: string;
  path?: string;
  children?: RepositoryNode[];
  relations?: RepositoryRelation[];
  defaultExpanded?: boolean;
};

type RepositoryRelation = {
  target: string;      // path of the target node
  label: string;       // human-readable relation label
  type?: RepositoryRelationType;
  description?: string;
  external?: boolean;
};