This page documents the development environment setup for contributing to maxGraph, including Node.js version requirements, initial installation, and common development workflows. For information about the build system and output formats, see Build System and Dual Format Output. For testing procedures, see Testing Strategy. For complete contribution guidelines, see Contributing Guidelines.
maxGraph requires a specific Node.js version to ensure consistency across development environments and CI/CD pipelines. The required version is defined in .nvmrc1
Required Version: Node.js 24
Version Management:
The Node.js version specified in .nvmrc is critical because:
Sources: .nvmrc1 README.md224 CLAUDE.md11 CONTRIBUTING.md120-123
maxGraph uses npm workspaces to manage multiple packages within a single repository. Understanding this structure is essential for development workflow.
Sources: README.md1-262 CLAUDE.md210-245
| Package | Directory | Purpose | Build Tool |
|---|---|---|---|
@maxgraph/core | packages/core/ | Core TypeScript library | TypeScript compiler |
@maxgraph/html | packages/html/ | Storybook interactive demos | Storybook + Vite |
@maxgraph/website | packages/website/ | Docusaurus documentation | Docusaurus |
@maxgraph/ts-support | packages/ts-support/ | TypeScript 3.8+ validation | TypeScript compiler |
ts-example | packages/ts-example/ | Full-featured TypeScript example | Vite |
ts-example-without-defaults | packages/ts-example-without-defaults/ | Tree-shakable TypeScript example | Vite |
ts-example-selected-features | packages/ts-example-selected-features/ | Selective feature TypeScript example | Vite |
js-example | packages/js-example/ | Full-featured JavaScript example | Webpack |
js-example-without-defaults | packages/js-example-without-defaults/ | Tree-shakable JavaScript example | Webpack |
js-example-selected-features | packages/js-example-selected-features/ | Selective feature JavaScript example | Webpack |
js-example-nodejs | packages/js-example-nodejs/ | Node.js headless example | Node.js |
ts-example-jest-commonjs | packages/ts-example-jest-commonjs/ | Jest testing example | Jest |
Sources: README.md144-162 CLAUDE.md236-244 packages/website/docs/demo-and-examples.md22-41
All commands must be executed from the repository root to properly initialize npm workspaces:
Why root installation is required:
Sources: README.md224-225 CONTRIBUTING.md110-130 CLAUDE.md16-19 .github/copilot-instructions.md20-30
After installation, verify the setup:
Sources: CLAUDE.md16-19 .github/copilot-instructions.md28-30
The primary development workflow involves watching and rebuilding the core library:
The dev command runs TypeScript compiler in watch mode, rebuilding ES modules in lib/esm/ whenever source files change. This command only builds ESM format for faster iteration (packages/core/package.json).
Sources: README.md227-229 CLAUDE.md22-27 CONTRIBUTING.md154-161
Storybook provides interactive examples demonstrating maxGraph features. Run it alongside core development for immediate visual feedback:
Storybook features:
Sources: README.md227-229 CLAUDE.md26-31 CONTRIBUTING.md154-163 packages/html/stories/Introduction.mdx30-61
Sources: README.md227-229 CONTRIBUTING.md154-163
Example applications demonstrate integration patterns with different build tools:
Each example demonstrates specific features:
Graph class with all defaultsBaseGraph with minimal configurationBaseGraph with explicit feature selection for tree-shakingBundle size verification:
The Vite configurations include chunkSizeWarningLimit to track bundle sizes:
Sources: README.md144-162 packages/website/docs/demo-and-examples.md22-41 packages/ts-example/vite.config.js1-33 packages/ts-example-without-defaults/vite.config.js1-33 packages/ts-example-selected-features/vite.config.js1-33
Sources: README.md232-234 CLAUDE.md34-43 CONTRIBUTING.md167-177
For comprehensive testing information, see Testing Strategy.
Sources: README.md235-237 CLAUDE.md46-61 CONTRIBUTING.md179-189
Sources: README.md235-237 CLAUDE.md64-79 CONTRIBUTING.md191-201
Sources: README.md223-239 CLAUDE.md13-31 CONTRIBUTING.md149-204
npm workspaces use the -w or --workspace flag to target specific packages:
Important: Some commands like npm run all are only available at the root level and run multiple workspace commands in sequence.
Sources: README.md223-237 CLAUDE.md13-90
Symptom: Cannot find module '@maxgraph/core' or similar errors
Solution:
Sources: .github/copilot-instructions.md291-303
Symptom: TypeScript compilation errors
Solution:
Sources: .github/copilot-instructions.md295-300
Symptom: Storybook shows outdated code or fails to load
Solution:
Sources: CLAUDE.md29-31
Symptom: Storybook fails to start with EADDRINUSE error
Solution:
Sources: CLAUDE.md26-27
| Task | Command | Notes |
|---|---|---|
| Initial setup | npm install | Run from repository root |
| Use Node.js version | nvm use | Reads from .nvmrc |
| Watch core library | npm run dev -w packages/core | ESM only, faster iteration |
| Run Storybook | npm run dev -w packages/html | Port 8901, hot reload enabled |
| Build everything | npm run all | Full build + tests |
| Run tests | npm test -w packages/core | Jest with jsdom |
| Lint code | npm run lint | ESLint + Prettier |
| Check circular deps | npm run check:circular-dependencies -w packages/core | Uses madge |
| Clean build artifacts | npm run clean -w packages/core | Removes lib/ directory |
Sources: README.md220-239 CLAUDE.md13-79
After completing the development setup:
Sources: README.md210-262 CONTRIBUTING.md1-335
Refresh this wiki