Neuron Explorer VS Code Extension

Developer Guide

Quick Start

From a clean checkout:

cd neuron-xray-extension
npm run setup:dev

This single command:

1. Installs UI dependencies
2. Builds and packs UI packages (dev mode with source maps)
3. Installs extension dependencies
4. Installs UI tarballs into node_modules/
5. Builds the extension

Then press F5 to debug.

Package.json Scripts

Setup & Install

Build Scripts

Package Scripts

Other Scripts

Build Architecture

The extension uses rollup to bundle src/extension.ts into a single CJS file (dist/extension.js). This is necessary because:

• VS Code's extension host loads extensions via require() (CommonJS)
• The UI packages use "type": "module" (ESM)
• Rollup handles the ESM→CJS conversion, avoiding TypeScript's strict CJS/ESM boundary enforcement

The tsconfig.json uses "module": "ESNext" + "moduleResolution": "bundler" for type-checking (no CJS/ESM errors in the editor), while rollup produces the actual CJS output.

Key files:

• rollup.config.extension.js — bundles src/extension.ts → dist/extension.js (CJS)
• rollup.config.js — bundles React webview components → dist/react-components/*.min.js
• tsconfig.json — type-checking config (ESNext/bundler, no emit)
• tsconfig.react.json — React components compilation → dist/react-components/

RELEASE_TYPE

The RELEASE_TYPE environment variable controls which features are enabled:

• external (default) — public release, internal features disabled
• internal — internal features enabled (AWS auth, upload, etc.)

It's baked in at build time by rollup's replace plugin. The default is external (safe) — internal must be explicitly set.

Resolving UI Dependencies

The extension depends on UI packages from ui/:

• neuron-explorer-code-editor
• neuron-explorer-common
• neuron-explorer-timeline-viewer
• neuron-explorer-ui-components

These are listed as optionalDependencies (with version "*") so npm install doesn't fail when they can't be resolved from a public registry.

Local dev: npm run setup handles everything — builds UI, packs tarballs, installs them.

After UI changes: Re-run the UI build and reinstall tarballs:

cd ../ui && npm run build:dev
cd ../neuron-xray-extension && npm run install:ui-components

Debugging (F5)

1. Run npm run setup:dev (first time) or npm run build:internal (subsequent)
2. Open neuron-xray-extension/ as the workspace in VS Code
3. Select "Run Extension (Internal Mode)" from the debug dropdown
4. Press F5

The watch task (triggered by F5's preLaunchTask) uses rollup in watch mode with RELEASE_TYPE=internal. It produces CJS output with source maps — breakpoints work.

Project Structure

• src/ - Source code
  • extension.ts - Main extension entry point
  • config/buildConfig.ts - Build-time configuration (RELEASE_TYPE)
  • react-components/ - React wrapper components for webviews
  • webViews/ - WebView panel implementations
  • listeners/ - Event listeners
  • services/ - Service modules
  • types/ - TypeScript type definitions
• dist/ - Compiled output
  • extension.js - Bundled extension (CJS, single file)
  • react-components/ - Bundled webview components
• build/vscode-extension-artifacts/ - Packaged .vsix files
• scripts/ - Build and utility scripts
  • setup.sh - Full local dev setup
  • install-ui-components.sh - Installs UI tarballs
• resources/ - Static resources (icons, etc.)

Adding Widgets

See AGENTS.md for a detailed step-by-step guide — including code templates and a completion checklist.

Summary of steps:

1. Verify base widget and widget type entries exist in ui/packages/common/src/services/types/Widget.types.ts
2. Create the VS Code widget component (<WidgetName>VSCode.tsx) and export it from widgets/index.ts
3. Create the React wrapper entry point in src/react-components/
4. Create the WebviewPanel class in src/webViews/
5. Register the panel in widgetManager.ts (import + switch case)
6. Add the widget to the sidebar dropdown in widgetsSidebar.ts