A first diagram
Declare components, give them attributes and connect them:
@layout(w:950,h:400)
browser:Browser(url: "https://shop.example.com", text: "Shop", x:50,y:100,w:200,h:150)
vps:VM(title: "prod@ubuntu", x:300,y:&browser.c,w:600,h:300) {
nginx:Server(title: "nginx", icon: "nginx", port: 80, x:50,y:&browser.c,w:200,h:50)
app:Server(title: "App", icon: "golang", port: 8080, x:350,y:&browser.c,w:200,h:50)
}
@browser.request(target: @nginx)
@nginx.request(target: @app)Examples
Each example is the complete source followed by the SVG it produces. Copy one into a .nagare file and render it with the CLI.
A checkout flow, animated
Components nest inside a VM. Each request line draws an arrow, with the sides worked out from the layout. A Database has activity lights, and the last two lines blink them for a write, then a read. The animation is plain SVG, so it plays wherever the image is shown, with no script.
@layout(w:1000,h:450)
shop:Browser(url: "https://shop.example.com", text: "Checkout", x:30,y:120,w:230,h:170)
gw:APIGateway(title: "gateway", method: "POST", route: "/orders", x:310,y:&shop.c,w:180,h:60)
vm:VM(title: "prod@ubuntu", x:540,y:40,w:430,h:200) {
api:Server(title: "orders-api", icon: "golang", port: 8080, x:30,y:60,w:170,h:50)
mailer:BackgroundWorker(title: "mailer", job: "send-receipt", x:240,y:60,w:160,h:50)
}
db:Database(title: "orders", engine: "postgres", x:570,y:300,w:120,h:120)
events:MessageQueue(title: "order.created", kind: "nats", x:770,y:325,w:200,h:70)
@shop.request(target: @gw)
@gw.request(target: @api)
@api.request(target: @db)
@api.request(target: @mailer)
@mailer.request(target: @events)
@db.write(begin:"0.5s",dur:"1.5s")
@db.read(begin:"2.5s",dur:"1.5s")Primary and replica
Give each action a begin and a dur to tell a story in order: the write lands on the primary, reaches the replica, and the report reads from the replica.
@layout(w:760,h:320)
api:Server(title: "orders-api", icon: "golang", port: 8080, x:40,y:130,w:200,h:56)
primary:Database(title: "primary", engine: "postgres", x:360,y:20,w:120,h:120)
replica:Database(title: "replica", engine: "postgres", x:360,y:180,w:120,h:120)
reports:Server(title: "reports", port: 9000, x:560,y:212,w:170,h:56)
@api.request(target: @primary)
@api.request(target: @replica)
@reports.request(target: @replica)
@primary.write(begin:"0.5s",dur:"1.5s")
@replica.write(begin:"2s",dur:"1s")
@replica.read(begin:"3.5s",dur:"1.5s")A publishing pipeline, dark theme
theme: dark in @layout switches the palette. y: &ci.c centres a component on another one, so the row stays aligned when sizes change.
@layout(w:1000,h:240,theme:dark)
ci:Terminal(title: "ci", cwd: "~/site", command: "gengo generate --plain", x:20,y:30,w:280,h:170)
dist:Artifact(title: "dist", filename: "site.tar.gz", size: "1.2 MB", x:350,y:&ci.c,w:170,h:60)
edge:CDN(title: "edge", provider: "pages", region: "global", x:570,y:&ci.c,w:170,h:60)
reader:Browser(url: "https://example.com/blog", text: "Blog", x:790,y:30,w:190,h:170)
@ci.request(target: @dist)
@dist.request(target: @edge)
@reader.request(target: @edge)A chart
Input that starts with chart is drawn as a chart. Series, colours and styles are pipe-separated, one column per series.
chart
title: Requests per second
xaxis: number
series: api | cache hits
color: #c8452c | #2f6f8f
style: line | dashed
data:
0: 120 | 40
1: 180 | 90
2: 260 | 170
3: 240 | 190
4: 310 | 260Install
The install script downloads the latest release for your platform, verifies its checksum and puts nagare in ~/.local/bin.
$ curl -fsSL https://raw.githubusercontent.com/saasuke-labs/nagare/main/install/install.sh | bashArchives for every platform are on the releases page.
Three ways to use it
Command line
Render a file to SVG:
$ nagare -input diagram.nagare -output diagram.svgHTTP server
Run nagare with no input file to start a server on port 8080 (change it with -port), then post diagram text to /render:
$ nagare -port 3000
$ curl -X POST http://localhost:3000/render \
-H "Content-Type: text/plain" \
--data-binary @diagram.nagareThe server also hosts a playground at its root URL: a live editor with instant preview, examples and diagrams saved in your browser.
Go library
$ go get github.com/saasuke-labs/nagareimport "github.com/saasuke-labs/nagare/pkg/nagare"
svg, err := nagare.RenderToSVG(diagramCode)
if err != nil {
log.Fatal(err)
}
fmt.Println(svg)
Syntax
Components
A component is id:Type(attributes). The id is optional; without one it is generated.
browser:Browser(url: "https://example.com", text: "Home")
db:Database(title: "orders")
Server(title: "worker")Available types: Browser, VM, Server, Terminal, Database, MessageQueue, CDN, APIGateway, BackgroundWorker, Package, Artifact, Rectangle, plus the primitives Cylinder and Led.
Position and size
x, y, w and h place a component. A value like y:&browser.c aligns to another component, here the centre of browser.
Nesting
Containers such as VM hold other components in a block. Children are positioned relative to their parent.
vps:VM(title: "ubuntu") {
nginx:Server(title: "nginx", port: 80)
app:Server(title: "App", port: 8080)
}Connections
A request action draws a solid arrow from one component to another, and a response action a dashed one. Nagare picks the sides to join from where the two components sit.
@browser.request(target: @nginx)
@nginx.response(target: @browser)Add dir to choose the direction yourself: lr, rl, tb or bt (left to right, right to left, top to bottom, bottom to top).
@api.request(target: @db, dir: tb)For full control, join two anchors directly. Anchors are compass points: n, ne, e, se, s, sw, w, nw.
browser.e --> nginx.wCanvas
A @layout line sets the canvas size, useful when a diagram has to fit a fixed space.
@layout(w: 800, h: 600)
Themes and colours
Every component is drawn from one visual system: the same card shape, stroke, corner radius and type scale, with an icon and accent colour per type. The canvas is transparent, so a diagram sits on whatever background the page has.
Pick the theme in the layout line. light is the default.
@layout(w: 800, h: 600, theme: dark)Colour attributes override the theme on a single component:
| Attribute | Applies to |
|---|---|
bg | Card, window chrome or cylinder fill. |
fg | Text colour. |
accent | Icon and highlight colour, where the component has one. |
contentBg | Content area of Browser and VM. |
If an fg override would be unreadable on its background, Nagare uses a contrasting text colour instead.
Charts
The same engine draws charts. A chart can mix series styles and axes in one definition:
series: jog | walk | total distance | jog blocks
style: bar | bar | line | marker
stack: session | session | none | none
yaxis: time | time | distance | blocks
type: duration | duration | number | numberline,dashedanddotteddraw lines.bardraws columns. Bar series that share astackgroup are stacked.markerdraws a point with its value above it.
Dates work on the x axis and durations on the y axis. Bar widths adapt to how dense the data is.
Inside a Gengo site
Gengo renders any nagare code block in your Markdown to an inline SVG at build time, with no exported image to keep in sync.
Licence
Nagare is open source under the MIT licence.