Docker Compose Flow

A VS Code extension that automatically visualizes your docker-compose.yml as an interactive dependency graph, detects common misconfigurations, and lets you inspect every service's config in one click.

Features

• Auto-opens when you switch to any docker-compose*.yml file
• Live reload — graph updates on every save (including external writes and git checkouts)
• Interactive graph — pan, zoom, minimap; click any node to isolate its dependency chain
• Issue detection — port conflicts, missing depends_on targets, circular dependencies, hardcoded secrets, exposed database ports, missing restart policies
• Service detail panel — image/build, ports, volumes, networks, env vars (secrets masked), healthcheck, per-service issues
• Selection isolation — clicking a service dims everything unrelated; click again to restore

Supported file patterns

docker-compose.yml · docker-compose.yaml · docker-compose.*.yml · docker-compose.*.yaml

Getting Started

Install from marketplace

Search "Docker Compose Flow" in the VS Code Extensions panel, or:

ext install xianmalik.docker-compose-flow

Install from a .vsix file

code --install-extension docker-compose-flow-0.1.0.vsix

Usage

1. Open any docker-compose.yml in VS Code — the visualizer panel opens automatically beside it.
2. Or run Docker Compose: Visualize from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. The toolbar button appears in the editor title bar when a compose file is active.

Development

Prerequisites

• Node.js 18+
• Bun 1.2+ (npm install -g bun)
• VS Code

Setup

git clone https://github.com/your-username/docker-compose-flow
cd docker-compose-flow
bun install

Build

# One-shot production build (extension host + webview)
bun run build

# Watch mode during active development (run in separate terminals)
bun run watch:ext      # esbuild watches src/ → dist/extension.js
bun run watch:webview  # Vite watches webview/ → dist/webview/

Run in VS Code (F5)

1. Open the repo in VS Code.
2. Press F5 (or use the Run & Debug panel → Run Extension).
3. A new Extension Development Host window opens.
4. Open or switch to any docker-compose.yml — the panel appears automatically.

The Run Extension launch config runs bun run build before launching. Use Run Extension (no rebuild) if you are already in watch mode.

Project structure

src/                    Extension host (Node.js, bundled with esbuild)
  extension.ts          activate(), command registration, editor-change listener
  ComposePanel.ts       Singleton WebviewPanel — file watcher, message bus

webview/                React app (browser, bundled with Vite)
  index.html            Vite HTML entry
  index.tsx             ReactDOM.createRoot
  App.tsx               3-panel layout + VS Code message bridge
  globals.css           Global styles (React Flow overrides)
  components/           ServiceGraph, ServiceNode, CustomEdge, IssuePanel,
                        ServiceDetailPanel, ComposeInput
  lib/                  parser.ts, analyzer.ts, layout.ts, normalize.ts, sample.ts
  types/                compose.ts — all TypeScript interfaces

images/
  icon.png              Extension icon — 128×128 PNG (add before publishing)

dist/                   Build output (git-ignored, regenerated by bun run build)
  extension.js
  webview/index.js
  webview/index.css

esbuild.mjs             Extension host build script
vite.config.ts          Webview build config
tsconfig.json           Extension host TypeScript (Node16, src/)
tsconfig.webview.json   Webview TypeScript (bundler, dom, webview/)

Message protocol

The extension host and webview communicate via postMessage:

Publishing

VS Code Marketplace + Open VSX (Cursor, Windsurf, Gitpod, Project IDX)

This guide covers both the official VS Code Marketplace and Open VSX Registry, which is used by every VS Code-compatible editor that isn't Microsoft VS Code (Cursor, Windsurf, Gitpod, Google Project IDX / Antigravity, etc.). Publish to both to reach all of them.

Step 1 — Create a publisher account

VS Code Marketplace

1. Sign in at marketplace.visualstudio.com/manage with a Microsoft account.
2. Click Create publisher, choose a publisher ID (e.g. yourname). This ID is permanent.
3. Go to dev.azure.com, create an organisation if you don't have one.
4. Click User settings → Personal Access Tokens → New Token:
   • Name: vsce-publish (or anything)
   • Organisation: All accessible organisations
   • Expiration: set a long date (max 1 year)
   • Scopes: Custom defined → tick Marketplace → Manage
5. Copy the token — you only see it once.

Open VSX

1. Sign in at open-vsx.org with a GitHub account.
2. Go to your profile → Access Tokens → create a token. Copy it.

Step 2 — Fill in the placeholders in package.json

{
  "publisher": "your-publisher-id",       // ← your Marketplace publisher ID
  "repository": {
    "url": "https://github.com/you/repo"  // ← your GitHub repo
  },
  "homepage":  "https://github.com/you/repo#readme",
  "bugs":      { "url": "https://github.com/you/repo/issues" }
}

Step 3 — Add the extension icon

• Create images/icon.png — 128 × 128 px PNG, ≤ 256 KB.
• Avoid transparency at the edges (the marketplace clips to a rounded rectangle).
• package.json already has "icon": "images/icon.png" wired up.

vsce package will error if the file is missing.

Step 4 — Bump the version and update the changelog

Follow Semantic Versioning:

# patch release (bug fixes)
npm version patch   # 0.1.0 → 0.1.1

# minor release (new features, backwards-compatible)
npm version minor   # 0.1.0 → 0.2.0

# major release (breaking changes)
npm version major   # 0.1.0 → 1.0.0

Then edit CHANGELOG.md — add a section for the new version before publishing.

Step 5 — Verify what goes into the package

# List every file that would be bundled into the .vsix
npx vsce ls --no-dependencies

The output should contain only:

dist/extension.js
dist/extension.js.map
dist/webview/index.js
dist/webview/index.css
images/icon.png
package.json
README.md
CHANGELOG.md
LICENSE   (if present)

If you see node_modules/, src/, or webview/, the .vscodeignore is wrong.

Step 6 — Build and package

# Runs bun run build internally, then packages
bun run package
# → docker-compose-flow-0.1.0.vsix

Install it locally to do a final smoke-test before publishing:

code --install-extension docker-compose-flow-0.1.0.vsix

Step 7 — Log in and publish

VS Code Marketplace

# First time (saves token to your keychain)
npx vsce login your-publisher-id
# enter the Azure DevOps PAT when prompted

# Publish (reads publisher + version from package.json)
bun run publish:vsce

Open VSX (Cursor / Windsurf / Gitpod / Project IDX)

# Publish directly from the .vsix — no separate login step needed
npx ovsx publish docker-compose-flow-0.1.0.vsix \
  --pat <your-open-vsx-token>

# Or set the token as an env var and use the npm script:
OVSX_PAT=<token> bun run publish:ovsx

Publish both at once

OVSX_PAT=<token> bun run publish
# runs publish:vsce then publish:ovsx

Pre-publish checklist

[ ] publisher ID updated in package.json
[ ] repository / homepage / bugs URLs updated in package.json
[ ] images/icon.png added (128×128 PNG, ≤ 256 KB)
[ ] version bumped (npm version patch|minor|major)
[ ] CHANGELOG.md updated for this version
[ ] bun run typecheck — no type errors
[ ] bun run build — succeeds
[ ] npx vsce ls --no-dependencies — only dist/ + metadata in list
[ ] local smoke-test: code --install-extension *.vsix, open a compose file
[ ] bun run publish:vsce (Marketplace)
[ ] bun run publish:ovsx (Open VSX)

Updating an existing release

# 1. Bump version
npm version patch

# 2. Update CHANGELOG.md

# 3. Build, package, verify
bun run package
npx vsce ls --no-dependencies

# 4. Publish
OVSX_PAT=<token> bun run publish

The Marketplace does not allow re-publishing the same version number. Always bump before publishing, even for hotfixes.

Tech stack

Contributing

Pull requests welcome. Run bun run typecheck before submitting to catch type errors in both the extension host and webview.

License

Copyright (c) 2025 Malik Zubayer Ul Haider (xianmalik).

See the LICENSE file for full terms.