Skip to content

Deployment Guide

This guide covers deploying NebulaFlow as a VS Code extension and Electron application, including versioning, packaging, and distribution.

Prerequisites

  • Node.js ≥ 18 and npm ≥ 9
  • VS Code ≥ 1.90.0 (for extension development)
  • Git (for version control)
  • VSCE (VS Code Extension CLI) - installed via npm install -g @vscode/vsce
  • Electron Builder (for Electron packaging) - installed via npm install -g electron-builder

Deployment Targets

NebulaFlow can be deployed in two ways:

1. VS Code Extension (Primary)

The extension is published to the VS Code Marketplace for installation by users.

2. Electron Application (Alternative)

A standalone desktop application that bundles VS Code and NebulaFlow, available as: - AppImage for Linux - DMG for macOS - NSIS installer for Windows

Build & Package Process

VS Code Extension Package

Create a .vsix file for distribution:

npm run package:vsix

This command: 1. Runs type checking (npm run typecheck) 2. Builds the webview (npm run build:webview) 3. Builds the extension (npm run build:ext) 4. Packages everything into dist/nebulaflow-{version}.vsix

Output: dist/nebulaflow-0.2.14.vsix (version matches package.json)

Electron Application Package

Build platform-specific installers:

# Build Electron app (main process)
npm run build:electron

# Create platform packages
npm run pack:electron  # Uses electron-builder

# Platform-specific builds
npm run pack:win       # Windows NSIS installer
npm run zip:win        # Windows zip package

Output: dist/release/ containing: - NebulaFlow-{version}.AppImage (Linux) - NebulaFlow-{version}.dmg (macOS) - NebulaFlow-{version}.exe (Windows NSIS)

Versioning Strategy

Automatic Versioning

The version is defined in package.json:

{
  "version": "0.2.14",
  "publisher": "prinova"
}

Release Process

  1. Update version in package.json (follow Semantic Versioning):
  2. Patch (0.2.14 → 0.2.15): Bug fixes
  3. Minor (0.2.14 → 0.3.0): New features (backward compatible)

  4. Major (0.2.14 → 1.0.0): Breaking changes

  5. Create a Git tag: 

    git tag v0.2.14
git push origin v0.2.14

  6. Build and package: 

    npm run package:vsix
npm run pack:electron

  7. Create GitHub Release:

  8. Go to GitHub → Releases → Draft New Release
  9. Use the tag v0.2.14
  10. Upload the .vsix file and platform installers
  11. Add release notes

VS Code Marketplace Deployment

Publishing to Marketplace

  1. Create a publisher account at Visual Studio Code Marketplace Publisher Portal

  2. Get a Personal Access Token:

  3. Go to Azure DevOps
  4. Create a new organization (or use existing)

  5. Generate a PAT with "Marketplace" (Publish) scope

  6. Publish the extension: 

    vsce publish --pat <your-personal-access-token>

Or publish a specific .vsix file: 

vsce publish --pat <your-personal-access-token> --vsix dist/nebulaflow-0.2.14.vsix

  1. Verify publication:
  2. Check the Marketplace Publisher Portal
  3. The extension will be available at: https://marketplace.visualstudio.com/items?itemName=prinova.nebulaflow

Marketplace Configuration

The extension's marketplace metadata is controlled by: - package.json fields: name, displayName, description, version, publisher - README.md (displayed on marketplace page) - CHANGELOG.md (version history)

Important: Update README.md before publishing to ensure accurate marketplace documentation.

GitHub Actions CI/CD

Build Workflow

The project includes a GitHub Actions workflow (.github/workflows/build.yml) that automatically:

  1. Triggers on:
  2. Pushes to main and dev branches
  3. Pull requests

  4. Tag pushes (e.g., v*)

  5. Runs: 

    npm run check          # Type check + lint
npm run package:vsix   # Build and package extension

  6. Uploads artifacts:

  7. VSIX file
  8. Build logs

  9. Test results

  10. Creates GitHub Release (when a tag is pushed):

  11. Auto-generates release notes
  12. Attaches build artifacts

Manual CI/CD Trigger

You can manually trigger the workflow: 

# Push a tag to trigger release
git tag v0.2.14
git push origin v0.2.14

Distribution Channels

Primary Distribution

  1. VS Code Marketplace (Recommended)
  2. Users install via VS Code Extensions view
  3. Automatic updates

  4. Professional distribution

  5. GitHub Releases

  6. Direct download of .vsix files
  7. Platform-specific installers
  8. Suitable for manual installation

Alternative Distribution

  1. GitHub Packages (Optional)
  2. Store .vsix files as GitHub Packages

  3. Private distribution for enterprise

  4. Manual Installation

  5. Users can install .vsix files directly: 
    code --install-extension nebulaflow-0.2.14.vsix

Deployment Checklist

Before Release

  • [ ] Run npm run check (typecheck + lint) - all errors fixed
  • [ ] Update version in package.json
  • [ ] Update CHANGELOG.md with release notes
  • [ ] Test extension in VS Code (F5 debug mode)
  • [ ] Test Electron app builds (if applicable)
  • [ ] Update README.md with current features
  • [ ] Verify all documentation links are valid

During Release

  • [ ] Create Git tag: git tag v{version}
  • [ ] Push tag: git push origin v{version}
  • [ ] Build VSIX: npm run package:vsix
  • [ ] Build Electron installers: npm run pack:electron
  • [ ] Create GitHub Release with artifacts
  • [ ] Publish to VS Code Marketplace

After Release

  • [ ] Verify marketplace listing is correct
  • [ ] Test installation from marketplace
  • [ ] Monitor GitHub Issues for bug reports
  • [ ] Update documentation if needed

Environment Variables for Deployment

Required for LLM Nodes

These must be set in the user's environment, not during build:

export OPENAI_API_KEY="your-openai-key"
export OPENROUTER_API_KEY="your-openrouter-key"

Optional Configuration

# Maximum shell output characters (default: 10000)
export NEBULAFLOW_SHELL_MAX_OUTPUT="50000"

# Enable LLM debug logging
export NEBULAFLOW_DEBUG_LLM="true"

# Filter pause seeds (for testing)
export NEBULAFLOW_FILTER_PAUSE_SEEDS="false"

Troubleshooting Deployment

Issue Solution
VSCE authentication failed Ensure PAT has "Marketplace (Publish)" scope and is not expired.
Build fails with type errors Run npm run typecheck and fix all errors before packaging.
Webview assets missing in VSIX Ensure npm run build:webview completed successfully.
Electron build fails Check electron-builder configuration in package.json; verify platform tools (e.g., NSIS for Windows).
Version mismatch Ensure package.json version matches the Git tag and release notes.
Marketplace rejection Verify README.md has no broken links and CHANGELOG.md follows proper format.
GitHub Actions fails Check workflow logs; ensure all dependencies are in package.json.
Extension not activating Verify main field points to dist/src/extension.js and file exists.

Rollback Strategy

If a release causes issues:

  1. Immediate rollback:
  2. Unpublish from VS Code Marketplace (via Publisher Portal)
  3. Remove GitHub Release

  4. Revert Git tag

  5. Hotfix release:

  6. Create a new branch from the previous stable tag
  7. Apply fixes
  8. Bump patch version

  9. Release as v{major}.{minor}.{patch+1}

  10. Communication:

  11. Update GitHub Issues
  12. Post in relevant channels (Discord, etc.)
  13. Update README if needed

Next Steps