Build System & Distribution

This document describes the monorepo build system, package structure, and distribution strategy for relation-graph. It covers how the shared core and platform-specific packages are built, bundled, and published to npm.

For information about the multi-platform architecture and how framework-specific components integrate with the core, see Multi-Platform Architecture.

Monorepo Structure

The relation-graph repository is organized as a monorepo containing a shared core and five platform-specific npm packages. Each platform package provides framework-specific bindings while sharing the same underlying core implementation.

graph TB
    Root["Root
package.json"]
    BuildScript["build-all.sh
Build Orchestration"]
    
    subgraph "Platform Packages"
        Vue3Pkg["@relation-graph/vue
platforms/vue3/package.json"]
        Vue2Pkg["@relation-graph/vue2
platforms/vue2/package.json"]
        ReactPkg["@relation-graph/react
platforms/react/package.json"]
        SveltePkg["@relation-graph/svelte
platforms/svelte/package.json"]
        WebCompPkg["@relation-graph/web-components
platforms/web-components/package.json"]
    end
    
    subgraph "Shared Dependencies"
        DevDeps["Development Dependencies
TypeScript, ESLint, Prettier"]
        TSConfig["TypeScript Configuration
Shared across packages"]
    end
    
    Root -->|calls| BuildScript
    BuildScript -->|builds| Vue3Pkg
    BuildScript -->|builds| Vue2Pkg
    BuildScript -->|builds| ReactPkg
    BuildScript -->|builds| SveltePkg
    BuildScript -->|builds| WebCompPkg
    
    Vue3Pkg -.->|uses| DevDeps
    Vue2Pkg -.->|uses| DevDeps
    ReactPkg -.->|uses| DevDeps
    SveltePkg -.->|uses| DevDeps
    WebCompPkg -.->|uses| DevDeps
    
    Vue3Pkg -.->|uses| TSConfig
    Vue2Pkg -.->|uses| TSConfig
    ReactPkg -.->|uses| TSConfig
    SveltePkg -.->|uses| TSConfig
    WebCompPkg -.->|uses| TSConfig

Root Package Configuration

The root package.json serves as the monorepo orchestrator and provides a single build command for all platforms:

Field	Value	Purpose
name	relation-graph	Root package name
version	3.0.3	Synchronized version across all packages
private	false	Allows publishing of sub-packages
scripts.build-all	sh ./build-all.sh	Builds all platform packages

The root package also defines shared development dependencies used across all platforms:

• TypeScript compiler (typescript: ^4.7.4)
• ESLint and plugins for Vue, React, and TypeScript
• Prettier for code formatting
• Type definitions (@types/node)

Build System Architecture

The build system follows a shell-script-based orchestration pattern where a single script coordinates building all platform packages.

graph LR
    Developer["Developer"]
    BuildAll["build-all.sh"]
    
    subgraph "Build Steps Per Platform"
        TypeScript["TypeScript Compilation
tsc"]
        Bundler["Module Bundling
UMD + ESM"]
        TypeGen["Type Definition Generation
.d.ts files"]
    end
    
    subgraph "Build Outputs"
        UMD["relation-graph.umd.js
Universal Module Definition"]
        ESM["relation-graph.mjs
ES Module"]
        Types["types/packages/platforms/[platform]/src/index.d.ts
TypeScript Definitions"]
    end
    
    Developer -->|npm run build-all| BuildAll
    BuildAll --> TypeScript
    TypeScript --> Bundler
    TypeScript --> TypeGen
    Bundler --> UMD
    Bundler --> ESM
    TypeGen --> Types

Build Orchestration Script

The build-all.sh script referenced in the root package coordinates the build process for all five platform packages. This script likely:

1. Compiles TypeScript source files to JavaScript
2. Bundles code into UMD and ESM formats
3. Generates TypeScript declaration files
4. Copies assets and styles
5. Prepares each platform package for npm publishing

Package Output Structure

Each platform package produces three primary output artifacts that support different consumption patterns:

graph TB
    Package["Platform Package
e.g., @relation-graph/react"]
    
    subgraph "Output Artifacts"
        UMD["relation-graph.umd.js
package.json: main, unpkg"]
        ESM["relation-graph.mjs
package.json: module"]
        Types["types/packages/platforms/[platform]/src/index.d.ts
package.json: types"]
    end
    
    subgraph "Consumption Methods"
        Script["Script Tag
CDN/unpkg"]
        ModernBuild["Modern Build Tool
Webpack, Vite, Rollup"]
        TypeScriptIDE["TypeScript/IDE
IntelliSense"]
    end
    
    Package --> UMD
    Package --> ESM
    Package --> Types
    
    UMD --> Script
    ESM --> ModernBuild
    Types --> TypeScriptIDE

UMD Format (Universal Module Definition)

The relation-graph.umd.js file provides a universal module that works in multiple environments:

• Browser global: Can be loaded via <script> tag, exposing a global variable
• AMD modules: Compatible with RequireJS
• CommonJS: Works with Node.js require()
• CDN delivery: Referenced by the unpkg field for services like unpkg.com

Both the main and unpkg fields point to this artifact, making it the default for legacy bundlers and CDN usage.

ESM Format (ES Modules)

The relation-graph.mjs file provides native ES module format:

• Tree-shaking support: Modern bundlers can eliminate unused code
• Static imports: Uses import/export syntax
• Module optimization: Better for production builds with Webpack, Rollup, or Vite

The module field points to this artifact, allowing modern bundlers to prefer ESM over UMD.

TypeScript Declaration Files

TypeScript declaration files provide type information for IDEs and TypeScript projects:

types/packages/platforms/[platform]/src/index.d.ts

Each platform has a different types path structure:

Platform	Types Path
Vue 3	./types/packages/platforms/vue3/src/index.d.ts
Vue 2	./types/packages/platforms/vue2/src/index.d.ts
React	./types/packages/platforms/react/src/index.d.ts
Svelte	./types/packages/platforms/svelte/src/index.d.ts
Web Components	./types/packages/platforms/svelte/src/index.d.ts (note: appears to reference svelte)

The centralized types/ directory suggests a unified TypeScript compilation step that generates declarations for all platforms.

Platform Package Configuration

Each platform package follows a consistent structure with platform-specific metadata.

Common Package Fields

All platform packages share the following configuration:

Field	Value	Description
version	3.0.3	Synchronized across all packages
license	MIT	Open source license
author	WanLian <seeksdream@qq.com>	Package maintainer
repository.url	git+https://github.com/seeksdream/relation-graph.git	GitHub repository
homepage	http://relation-graph.com	Documentation website

Platform-Specific Package Names

Each package has a scoped name under the @relation-graph organization:

graph TB
    Org["@relation-graph
npm organization"]
    
    Org --> Vue3["@relation-graph/vue
Vue 3 support"]
    Org --> Vue2["@relation-graph/vue2
Vue 2 support"]
    Org --> React["@relation-graph/react
React support"]
    Org --> Svelte["@relation-graph/svelte
Svelte support"]
    Org --> WebComp["@relation-graph/web-components
Framework-agnostic"]
    
    subgraph "Usage Examples"
        VueInstall["npm install @relation-graph/vue"]
        ReactInstall["npm install @relation-graph/react"]
        SvelteInstall["npm install @relation-graph/svelte"]
    end
    
    Vue3 -.-> VueInstall
    React -.-> ReactInstall
    Svelte -.-> SvelteInstall

Keywords and SEO

Each package includes extensive keywords for npm search discoverability. The keywords are platform-specific and include both English and Chinese terms:

Vue 3 Package Keywords:

• relation-graph vue version
• vue relationship graph
• vue knowledge graph
• vue 关系图谱 (Chinese: relationship graph)
• vue 知识图谱 (Chinese: knowledge graph)

React Package Keywords:

• relation-graph react version
• react relationship graph
• react graph editor
• react 图谱编辑器 (Chinese: graph editor)

Development Dependencies

All platform packages share identical development dependencies, managed at the root level:

graph TB
    subgraph "TypeScript Toolchain"
        TS["typescript: ^4.7.4"]
        TSTypes["@types/node: *"]
        TSESLint["@typescript-eslint/eslint-plugin: ^5.30.0
@typescript-eslint/parser: ^5.30.0"]
    end
    
    subgraph "Code Quality Tools"
        ESLint["eslint: ^8.50.0"]
        Prettier["prettier: ^2.7.1"]
        ESLintConfig["eslint-config-prettier: ^6.12.0
eslint-config-standard: ^16.0.3"]
    end
    
    subgraph "Framework-Specific Linting"
        ESLintVue["eslint-plugin-vue: ^8.7.1
vue-eslint-parser: ^9.3.1"]
        ESLintReact["eslint-plugin-react: ^7.21.5"]
    end
    
    subgraph "Other Plugins"
        ESLintImport["eslint-plugin-import: ^2.28.1"]
        ESLintNode["eslint-plugin-node: ^11.1.0"]
        ESLintPromise["eslint-plugin-promise: ^5.1.0"]
        YAMLParser["yaml-eslint-parser: ^1.0.1"]
    end
    
    TS --> TSTypes
    ESLint --> ESLintConfig
    ESLint --> Prettier
    ESLint --> ESLintVue
    ESLint --> ESLintReact
    ESLint --> ESLintImport
    ESLint --> ESLintNode
    ESLint --> ESLintPromise

These dependencies support:

• TypeScript compilation with version 4.7.4
• Multi-framework linting with Vue and React plugins
• Code formatting with Prettier
• Standard JavaScript code style enforcement
• YAML parsing for configuration files

Version Management

All packages maintain synchronized version numbers, currently at 3.0.3. This synchronized versioning strategy:

1. Simplifies dependency management: Users know compatible versions across packages
2. Enables atomic releases: All platforms are released together
3. Maintains API consistency: Version numbers reflect shared core changes

graph LR
    Release["Release 3.0.3"]
    
    subgraph "All Packages at v3.0.3"
        Vue3["@relation-graph/vue"]
        Vue2["@relation-graph/vue2"]
        React["@relation-graph/react"]
        Svelte["@relation-graph/svelte"]
        WebComp["@relation-graph/web-components"]
    end
    
    Release --> Vue3
    Release --> Vue2
    Release --> React
    Release --> Svelte
    Release --> WebComp

Distribution via npm

Each platform package is published independently to npm under the @relation-graph scope. The packages have no runtime dependencies, making them lightweight additions to any project.

Zero Runtime Dependencies

All platform packages specify empty dependencies:

"dependencies": {}

This indicates that:

• The bundled code includes all necessary core logic
• No external libraries are required at runtime
• Users only need framework-specific peer dependencies (Vue, React, or Svelte)

Package Entry Points

Each package defines multiple entry points for different module systems:

graph TB
    NPMRegistry["npm Registry
@relation-graph/[platform]"]
    
    subgraph "Package Metadata"
        Main["main: relation-graph.umd.js
Legacy bundlers, Node.js"]
        Module["module: relation-graph.mjs
Modern bundlers with ESM support"]
        Unpkg["unpkg: relation-graph.umd.js
CDN delivery"]
        Types["types: types/packages/platforms/[platform]/src/index.d.ts
TypeScript definitions"]
    end
    
    subgraph "Consumer Tools"
        Webpack["Webpack"]
        Rollup["Rollup"]
        Vite["Vite"]
        CDN["unpkg.com"]
        IDE["VS Code / WebStorm"]
    end
    
    NPMRegistry --> Main
    NPMRegistry --> Module
    NPMRegistry --> Unpkg
    NPMRegistry --> Types
    
    Main --> Webpack
    Module --> Rollup
    Module --> Vite
    Unpkg --> CDN
    Types --> IDE

Installation Examples

Users install platform-specific packages based on their framework:

Vue 3 Project:

npm install @relation-graph/vue

Vue 2 Project:

npm install @relation-graph/vue2

React Project:

npm install @relation-graph/react

Svelte Project:

npm install @relation-graph/svelte

Framework-agnostic (Web Components):

npm install @relation-graph/web-components

Build Process Flow

The complete build process follows these stages:

flowchart TD
    Start["Developer runs:
npm run build-all"]
    BuildScript["build-all.sh
Executes"]
    
    subgraph "Per-Platform Build Steps"
        Clean["Clean Previous Build
Remove dist/"]
        TSCompile["TypeScript Compilation
tsc --project tsconfig.json"]
        Bundle["Module Bundling
Create UMD + ESM"]
        TypeGen["Generate Type Definitions
Extract .d.ts files"]
        CopyAssets["Copy Assets
SCSS, static files"]
    end
    
    subgraph "Build Artifacts"
        UMD["relation-graph.umd.js"]
        ESM["relation-graph.mjs"]
        Types["types/**/*.d.ts"]
        Styles["CSS/SCSS files"]
    end
    
    subgraph "Package Preparation"
        UpdatePkg["Update package.json
Verify entry points"]
        ValidatePkg["Validate Package
npm pack --dry-run"]
    end
    
    Ready["Ready for Publishing
npm publish"]
    
    Start --> BuildScript
    BuildScript --> Clean
    Clean --> TSCompile
    TSCompile --> Bundle
    TSCompile --> TypeGen
    Bundle --> CopyAssets
    TypeGen --> CopyAssets
    
    Bundle --> UMD
    Bundle --> ESM
    TypeGen --> Types
    CopyAssets --> Styles
    
    UMD --> UpdatePkg
    ESM --> UpdatePkg
    Types --> UpdatePkg
    Styles --> UpdatePkg
    
    UpdatePkg --> ValidatePkg
    ValidatePkg --> Ready

Repository Metadata

All packages share common repository and documentation metadata:

Field	Value	Purpose
repository.type	git	Version control system
repository.url	git+https://github.com/seeksdream/relation-graph.git	Source code location
homepage	http://relation-graph.com	Documentation and demos
bugs.url	https://github.com/seeksdream/relation-graph/issues	Issue tracking
directories.doc	doc	Documentation directory
directories.example	examples	Example applications

Directory Structure

The monorepo likely follows this structure:

relation-graph/
├── package.json                          # Root package
├── build-all.sh                          # Build orchestration script
├── tsconfig.json                         # Shared TypeScript config
├── packages/
│   └── core/                            # Shared core implementation
│       ├── src/
│       └── types/
├── platforms/
│   ├── vue3/
│   │   ├── package.json                 # @relation-graph/vue
│   │   ├── src/                         # Vue 3 components
│   │   ├── relation-graph.umd.js        # Build output
│   │   ├── relation-graph.mjs           # Build output
│   │   └── types/                       # Generated type definitions
│   ├── vue2/
│   │   ├── package.json                 # @relation-graph/vue2
│   │   └── ...
│   ├── react/
│   │   ├── package.json                 # @relation-graph/react
│   │   └── ...
│   ├── svelte/
│   │   ├── package.json                 # @relation-graph/svelte
│   │   └── ...
│   └── web-components/
│       ├── package.json                 # @relation-graph/web-components
│       └── ...
├── doc/                                 # Documentation
└── examples/                            # Example applications

This structure enables:

• Shared core logic: All platforms reference the same core implementation
• Platform isolation: Each platform has its own build outputs
• Independent publishing: Packages can be published separately if needed
• Centralized tooling: Build tools and configurations are shared