Kianda VS Code Editor
Edit, version, and publish Kianda widgets directly from VS Code — with offline support, Git integration, and explicit control over what gets published.
This extension is designed for web developers who prefer working locally with real files (.js, .hbs, .css) instead of in-browser editors.
✨ What this extension does
- Opens Kianda widgets in a local VS Code workspace
- Lets you edit offline
- Supports Git-based local versioning
- Allows explicit Publish (no auto-sync surprises)
- Handles version conflicts safely
- Works with enterprise tenants (custom app URLs)
🧠 Mental model (important)
Think of this extension as:
Local workspace = source of truth while you work
Server = publish target
- Files are downloaded once, then edited locally
- Nothing is sent to the server until you click Publish
- New widgets are created only on publish, not when files appear
- Versions are checked before publishing to avoid overwriting others’ work
🚀 Getting started
1. Install the extension
Install the extension from the VS Code Marketplace (or via .vsix if private).
2. Open a Kianda app in VS Code
From the Kianda web app, click:
Edit in VS Code
This will:
- Launch VS Code
- Authenticate securely
- Ask which widgets/files you want to download
- Create (or reopen) a local workspace
📦 Workspace structure
The extension follows an Ember-style layout:
your-workspace/
├─ components/
│ ├─ rules/
│ │ ├─ ruleA.js
│ │ └─ ruleA.hbs
│ ├─ fields/
│ │ ├─ fieldX.js
│ │ └─ fieldX.hbs
│ └─ widgets/
│ ├─ widgetY.js
│ └─ widgetY.hbs
├─ styles/
│ └─ app.css
├─ js/
│ └─ app.js
└─ .kianda/
└─ workspace.json
| Widget type |
Folder |
0 |
components/rules |
1 |
components/fields |
2 |
components/widgets |
Each widget consists of two files:
{id}.js – logic{id}.hbs – template
📋 Selecting what to download
On first load (and when using Add/Refresh Widgets), you’ll see a checkbox list:
- ✅ Download All
- app.css
- app.js
- Individual widgets (with type + version info)
This lets you:
- Keep workspaces small
- Work on only what you need
- Add more widgets later
🔄 Commands & workflow
The extension adds two buttons to the VS Code status bar:
- ☁️ Kianda Publish
- 🔄 Kianda Add/Refresh
Use this when you want to:
- Download widgets you didn’t select initially
- Refresh selected widgets from the server
- Optionally include
app.css / app.js
This does not publish anything.
- Refreshes only widgets already downloaded
- Does not add new widgets
- No prompt (safe refresh)
Kianda: Publish
This is the only operation that updates the server.
On publish, the extension will:
Discover new local widget pairs
{id}.js + {id}.hbs not yet on the server
Ask if you want to create them on the server
For each widget:
PUT the widget
- Server auto-increments the version
Update local version metadata
Nothing is published without your confirmation.
⚠️ Version conflicts (how they’re handled)
If someone else updated a widget after you downloaded it:
This prevents accidental overwrites.
🔐 Authentication (how it works)
Initial auth happens when you click Edit in VS Code
The extension receives:
- an access token
- a refresh token
Refresh tokens are stored securely using VS Code’s Secret Storage
Tokens are refreshed silently
You can:
- close VS Code
- reopen later
- still publish without re-authing
Credentials are stored per tenant, so multiple Kianda environments are supported.
🧾 Git integration (optional but recommended)
If Git is available:
- A repo is initialized automatically
.gitignore is created- Initial download can be committed
- Each publish can create a commit and tag
This gives you:
- Local history
- Diffs before publish
- Easy rollback
Git is local only — the extension does not push to remotes.
🪵 Logs & debugging
The extension logs to:
Output → Kianda
You’ll see:
- Download actions
- Publish steps
- Widget creation
- Version conflicts
- Errors
If something doesn’t behave as expected, this is the first place to look.
🧩 Configuration
Available settings (Settings → Kianda):
- Workspace root (where local workspaces are created)
- Enable/disable Git integration
- Auto-commit on download
- Auto-commit on publish
These are optional — defaults work out of the box.
❓ Common questions
Does editing files automatically update the server?
No. Only Publish updates the server.
Can I work offline?
Yes. Download once, edit offline, publish later.
No. Widgets are created only during Publish, after confirmation.
Can I use multiple tenants?
Yes. Each tenant has its own workspace and credentials.
🛠️ Who this is for
- Web developers
- JavaScript / HTML / CSS users
- Developers who prefer local tools over in-browser editors
- Teams that care about version control and safe publishing
📣 Feedback & next steps
This extension is designed to grow. Future improvements may include:
- Tree view of widgets
- Inline diffs against server
- CI-friendly publish validation
- Webview-based previews
Your feedback as a developer is essential — especially around UX and workflow.
Happy coding 🚀
