Learningmap is an open-source tool for creating, sharing, and exploring learning pathways. It's a monorepo built with React, TypeScript, and pnpm workspaces.

- **Website**: https://learningmap.app

- **Documentation**: https://learningmap.openpatch.org

- **Repository**: https://github.com/openpatch/learningmap

- **Maintainer**: Mike Barkmin (@mikebarkmin)

This is a **pnpm monorepo** with multiple packages and platforms:

- **Language**: TypeScript

- **UI Framework**: React 19

- **Package Manager**: pnpm (required - version >= 8)

- **Build Tool**: Vite + esbuild

- **Visual Editor**: ReactFlow (@xyflow/react)

- **Layout Engine**: ELK.js for auto-layout

- **Testing**: Vitest

- **Documentation**: Hyperbook

- **Version Management**: Changesets

- **Code Quality**: Prettier, Husky

pnpm install # Install all dependencies

pnpm build # Build all packages

pnpm test # Run tests across all packages

pnpm lint # Type-check with TypeScript

pnpm docs:dev # Start documentation dev server

pnpm dev # Watch mode for development

1. **Always use pnpm** - The project enforces pnpm usage via preinstall hook

2. **Build before testing** - Packages depend on each other's built artifacts

3. **Use Changesets** - For version management and changelog generation

4. **Follow existing patterns** - Match code style and structure of existing files

Each package has its own scripts defined in its `package.json`:

- `build`: Compiles TypeScript and bundles with esbuild

- `lint`: Type-checks with TypeScript (tsc --noEmit)

- `test`: Runs tests with Vitest

- Use strict TypeScript with proper type definitions

- Prefer interfaces for props and types for unions/intersections

- Export types alongside components

- No implicit `any` - always define types

- Use functional components with hooks

- Prefer named exports for components

- Use TypeScript interfaces for component props

- Follow existing patterns for event handlers (e.g., `on` prefix)

- Keep components focused and modular

- Components in PascalCase (e.g., `EditorToolbar.tsx`)

- Utilities and helpers in camelCase (e.g., `helper.ts`, `translations.ts`)

- Index files export public API

- Keep related code together

The project supports internationalization (i18n):

- Translations are defined in `packages/learningmap/src/translations.ts`

- Use the `getTranslations(language)` helper

- Default language is English (`en`), German (`de`) is also supported

- Always add translations for both languages when adding new strings

1. Implement the feature in the appropriate package

2. Add TypeScript types for all new props/interfaces

3. Update translations if adding user-facing text

4. Consider both editor and viewer modes

5. Test in both debug and preview modes

6. Update documentation if it's a public API change

The core editor (`LearningMapEditor`) has two modes:

- **Edit Mode**: Full editing capabilities with toolbar

- **Preview Mode**: View-only mode for testing the learner experience

Key components:

- `EditorToolbar`: Main menu and controls

- `EditorDrawer`: Side panel for node/edge editing

- Node types: `TopicNode`, `TaskNode`, `TextNode`, `ImageNode`

- Edge types: Regular edges, completion edges, unlock edges

- CSS is bundled with components

- Use existing CSS classes and patterns

- Follow the visual design of existing components

- Test in both light and dark modes (if applicable)

- Tests are run with Vitest

- Test files should be placed alongside source files

- Currently minimal test coverage - focus on core functionality

- Run tests with `pnpm test` before submitting PRs

Documentation is built with Hyperbook and located in the `docs/` directory:

- `docs/book/index.md`: Main documentation entry

- `docs/book/development.md`: Development guide

- `docs/book/contributing.md`: Contribution guidelines

- Update docs when adding features that affect the public API

GitHub Actions workflows:

- `pull-request.yml`: Runs tests and build on PRs

- `changeset-version.yml`: Manages version bumps and releases

- `docs.yml`: Deploys documentation

All PRs must pass:

1. TypeScript type checking (`pnpm lint`)

2. Tests (`pnpm test`)

3. Build (`pnpm build`)

- **No force pushes** - Git force push is disabled

- **No rebase** - Use merge commits for combining branches

- **Minimal changes** - Make the smallest possible changes to achieve goals

- **Preserve working code** - Don't remove or modify working code unless necessary

- **Follow existing patterns** - Match the style and structure of existing code

- **Use ecosystem tools** - Prefer pnpm scripts and package tools over manual changes

When adding new dependencies:

- Add to the appropriate package's `package.json`

- Use `pnpm add <package>` in the package directory

- Consider bundle size impact for the web component

- Prefer peer dependencies for React and related packages

- ❌ Don't use `npm` or `yarn` - always use `pnpm`

- ❌ Don't commit built artifacts (`dist/` folders)

- ❌ Don't modify `node_modules` or `pnpm-lock.yaml` manually

- ❌ Don't skip the build step - packages depend on each other

- ❌ Don't add tests that don't exist - follow existing test patterns

- ✅ Do run `pnpm install` after pulling changes

- ✅ Do run `pnpm build` before running tests

- ✅ Do commit your changes using the Changesets workflow

- ✅ Do test in both editor and preview modes

- **Issues**: Open an issue on GitHub for bugs or feature requests

- **Community**: Join the Matrix community at https://matrix.to/#/#openpatch:matrix.org

- **Contact**: Reach out to [email protected] for support

MIT License - maintained by OpenPatch (https://openpatch.org)