diagrams-js
Version:
A TypeScript port of the diagrams Python library for drawing cloud system architecture diagrams as code
300 lines (201 loc) • 5.65 kB
Markdown
---
name: diagrams-js/python-migration
description: >
Migrating from Python diagrams library to TypeScript. Converting context managers to function calls,
>> operator to .to(), << operator to .from(), - operator to .with(), Cluster syntax, import paths.
Key differences: explicit diagram.add(), async render(), no destroy().
type: lifecycle
library: diagrams-js
library_version: "0.5.0"
requires:
- diagrams-js/getting-started
sources:
- "hatemhosny/diagrams-js:docs/docs/guides/migration.mdx"
---
This skill builds on diagrams-js/getting-started. Read it first for foundational concepts.
# diagrams-js — Python Migration
Migrate from Python diagrams to TypeScript diagrams-js. Key syntax differences: context managers become function calls, operators become methods, explicit add() and async render().
## Setup
### Python vs TypeScript Side by Side
**Python:**
```python
from diagrams import Diagram
from diagrams.aws.compute import EC2
with Diagram("My Diagram", show=False):
EC2("Web Server")
```
**TypeScript:**
```typescript
import { Diagram } from "diagrams-js";
import { EC2 } from "diagrams-js/aws/compute";
const diagram = Diagram("My Diagram");
diagram.add(EC2("Web Server"));
const svg = await diagram.render();
```
## Core Patterns
### Creating Diagrams
**Python:**
```python
from diagrams import Diagram
from diagrams.aws.compute import EC2
with Diagram("My Diagram", show=False):
EC2("Web Server")
```
**TypeScript:**
```typescript
import { Diagram } from "diagrams-js";
import { EC2 } from "diagrams-js/aws/compute";
const diagram = Diagram("My Diagram");
diagram.add(EC2("Web Server"));
const svg = await diagram.render();
```
### Adding Nodes
**Python:**
```python
web = EC2("Web Server") # Auto-registered
```
**TypeScript:**
```typescript
const web = diagram.add(EC2("Web Server")); // Explicit registration
```
### Connections
**Python:**
```python
web >> api >> database
api >> storage
```
**TypeScript:**
```typescript
web.to(api).to(database);
api.to(storage);
```
### Reverse Connections
**Python:**
```python
database << api
```
**TypeScript:**
```typescript
database.from(api);
```
### Undirected Connections
**Python:**
```python
primary - replica
```
**TypeScript:**
```typescript
primary.with(replica);
```
### Multiple Connections
**Python:**
```python
lb >> [web1, web2, web3]
[worker1, worker2] >> database
```
**TypeScript:**
```typescript
lb.to([web1, web2, web3]);
[worker1, worker2].forEach((w) => w.to(database));
```
### Clusters
**Python:**
```python
from diagrams import Cluster
with Diagram("Services"):
with Cluster("Web Tier"):
web1 = EC2("web1")
web2 = EC2("web2")
```
**TypeScript:**
```typescript
const diagram = Diagram("Services");
const webTier = diagram.cluster("Web Tier");
const web1 = webTier.add(EC2("web1"));
const web2 = webTier.add(EC2("web2"));
```
### Edge Styling
**Python:**
```python
from diagrams import Edge
web >> Edge(color="red") >> db
```
**TypeScript:**
```typescript
import { Edge } from "diagrams-js";
web.to(Edge({ color: "red" }), db);
```
### Custom Nodes
**Python:**
```python
from diagrams.custom import Custom
Custom("Product", "https://mywebsite.com/icon.png")
```
**TypeScript:**
```typescript
import { Custom } from "diagrams-js";
diagram.add(Custom("Product", "https://mywebsite.com/icon.png"));
```
### Import Paths
| Python | TypeScript |
| --------------------------------------- | ------------------------------------------------ |
| `from diagrams.aws.compute import EC2` | `import { EC2 } from "diagrams-js/aws/compute"` |
| `from diagrams.aws.database import RDS` | `import { RDS } from "diagrams-js/aws/database"` |
| `from diagrams.gcp.compute import GCE` | `import { GCE } from "diagrams-js/gcp/compute"` |
| `from diagrams.k8s.compute import Pod` | `import { Pod } from "diagrams-js/k8s/compute"` |
## Common Mistakes
### CRITICAL Using Python context manager (with statement)
Wrong:
```typescript
with Diagram("Test"): // Python syntax - invalid in TypeScript
EC2("Web")
```
Correct:
```typescript
const diagram = Diagram("Test");
diagram.add(EC2("Web"));
const svg = await diagram.render();
```
TypeScript uses function calls, not Python context managers. Create diagram with Diagram(), add nodes with diagram.add().
Source: docs/guides/migration.mdx
### HIGH Forgetting explicit render() call
Wrong:
```typescript
const diagram = Diagram("Test");
diagram.add(EC2("Web"));
// Missing await diagram.render()
```
Correct:
```typescript
const diagram = Diagram("Test");
diagram.add(EC2("Web"));
const svg = await diagram.render();
```
Python auto-renders when context exits. TypeScript requires explicit render() call and await.
Source: docs/guides/migration.mdx
### CRITICAL Using Python list >> node syntax
Wrong:
```typescript
[web1, web2] >> database; // Python syntax
```
Correct:
```typescript
[web1, web2].forEach((w) => w.to(database));
```
TypeScript arrays don't have >> operator. Use forEach with method calls.
Source: docs/guides/migration.mdx
### HIGH Not importing nodes from correct paths
Wrong:
```typescript
import { EC2 } from "diagrams-js/aws"; // Missing category
```
Correct:
```typescript
import { EC2 } from "diagrams-js/aws/compute";
```
Provider paths are specific: diagrams-js/{provider}/{category}
Source: migration guide
## See also
- diagrams-js/provider-nodes — Provider import paths
- diagrams-js/node-connections — Connection method syntax
- diagrams-js/clusters-grouping — Cluster creation syntax