Installation

Comprehensive installation options for different environments and frameworks.

npm / yarn

The recommended way to install Graphty:

# npm
npm install @graphty/graphty-element

# yarn
yarn add @graphty/graphty-element

# pnpm
pnpm add @graphty/graphty-element

Then import in your JavaScript/TypeScript:

import '@graphty/graphty-element';

CDN Usage

For quick prototyping or simple pages, use a CDN:

<!-- unpkg -->
<script type="module" src="https://unpkg.com/@graphty/graphty-element"></script>

<!-- jsDelivr -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@graphty/graphty-element"></script>

Then use the component directly:

<graphty-element
  node-data='[{"id": "a"}, {"id": "b"}]'
  edge-data='[{"source": "a", "target": "b"}]'>
</graphty-element>

Framework Integration

React

Web Components work in React with some considerations:

import '@graphty/graphty-element';

function GraphVisualization({ nodes, edges }) {
  return (
    <graphty-element
      node-data={JSON.stringify(nodes)}
      edge-data={JSON.stringify(edges)}
      style={{ width: '100%', height: '500px', display: 'block' }}
    />
  );
}

For accessing the Graph instance:

import { useRef, useEffect } from 'react';
import '@graphty/graphty-element';

function GraphVisualization() {
  const graphRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const element = graphRef.current;
    if (element) {
      const graph = (element as any).graph;
      graph.zoomToFit();
    }
  }, []);

  return <graphty-element ref={graphRef} />;
}

Vue

Vue 3 supports Web Components with custom element configuration:

<script setup>
import '@graphty/graphty-element';
import { ref, onMounted } from 'vue';

const graphRef = ref(null);
const nodes = [{ id: 'a' }, { id: 'b' }];
const edges = [{ source: 'a', target: 'b' }];

onMounted(() => {
  const graph = graphRef.value.graph;
  graph.zoomToFit();
});
</script>

<template>
  <graphty-element
    ref="graphRef"
    :node-data="JSON.stringify(nodes)"
    :edge-data="JSON.stringify(edges)"
    style="width: 100%; height: 500px; display: block;"
  />
</template>

In vite.config.js, configure Vue to recognize the custom element:

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'graphty-element'
        }
      }
    })
  ]
}

Angular

Angular requires schema configuration for custom elements:

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})
export class AppModule {}

Then in your component:

import '@graphty/graphty-element';

@Component({
  template: `
    <graphty-element
      [attr.node-data]="nodesJson"
      [attr.edge-data]="edgesJson"
      style="width: 100%; height: 500px; display: block;">
    </graphty-element>
  `
})
export class GraphComponent {
  nodesJson = JSON.stringify([{ id: 'a' }, { id: 'b' }]);
  edgesJson = JSON.stringify([{ source: 'a', target: 'b' }]);
}

Peer Dependencies

Graphty has peer dependencies on Babylon.js and Lit:

{
  "peerDependencies": {
    "@babylonjs/core": "^8.0.0",
    "lit": "^3.0.0"
  }
}

These are typically installed automatically. If you need to install them manually:

npm install @babylonjs/core lit

TypeScript Setup

Graphty includes TypeScript definitions. Import types as needed:

import '@graphty/graphty-element';
import type { Graph, Node, Edge, StyleSchema } from '@graphty/graphty-element';

// Access the Graph instance
const element = document.querySelector('graphty-element');
const graph: Graph = (element as any).graph;

Bundle Size Considerations

Graphty bundles Babylon.js core, which adds to bundle size. For production:

1. Tree Shaking: The library supports tree shaking. Only import what you need.

2. External Babylon.js: If you're already using Babylon.js, configure your bundler to use the external version:

   // vite.config.js
   export default {
     build: {
       rollupOptions: {
         external: ['@babylonjs/core']
       }
     }
   }

3. Lazy Loading: Load Graphty only when needed:

   // Load on demand
   const loadGraph = async () => {
     await import('@graphty/graphty-element');
     // Now the component is registered
   };

Troubleshooting

Component Not Rendering

Ensure the element has explicit dimensions:

graphty-element {
  display: block;
  width: 800px;
  height: 600px;
}

Module Resolution Errors

If using TypeScript with moduleResolution: "node", you may need to use "bundler" or "node16":

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

WebGL Not Available

Graphty requires WebGL. Check browser support:

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
if (!gl) {
  console.error('WebGL is not supported');
}