Developing & Publishing Apps in VS Code

This guide explains how to develop, compile, and publish Niksphere applications using the official Niksphere VS Code Extension.

Prerequisites

1. Visual Studio Code (v1.80.0 or later).
2. Niksphere VS Code Extension installed.
3. Niksphere CLI (nik) installed (see Niksphere CLI Installation & Setup Guide)
4. Niksphere Engine local/remote instance (see Niksphere Engine Installation & Setup Guide) or a cloud environment.

1. Opening a Niksphere App Project

When you open a folder containing a nikapp.yaml manifest, the extension automatically activates:

• The Niksphere icon appears in the Activity Bar.
• The Publish App action appears in the bottom status bar.
• Language tooling (LSP, syntax highlighting, and UID autocompletion) starts automatically.

my-niksphere-app/
├── nikapp.yaml          # Core application manifest
├── entities/            # Entity declarations (YAML / Pascal)
│   └── Customer.yaml
├── pages/               # Server-driven UI definitions
│   └── CustomerList.yaml
└── units/               # Pascal business logic & event handlers
    └── CustomerEvents.pas

2. Editor Features & Language Tooling

Language Server Protocol (LSP)

The extension connects directly to the Niksphere Language Server via nik dev lsp. As you type:

• Errors in nikapp.yaml and .pas files are highlighted with squiggly lines.
• Missing mandatory fields or malformed Pascal syntax produce immediate IDE diagnostics in the Problems tab.

UID Autocompletion

When defining entities or fields in nikapp.yaml, the extension suggests new, collision-free alphanumeric UIDs whenever you press space or : on an ID line.

3. Compiling an App (Ctrl+Shift+B)

To validate and compile your application without deploying it:

1. Press Ctrl+Shift+B (or Cmd+Shift+B on macOS), or open the Command Palette (Ctrl+Shift+P) and choose Niksphere: Compile App.
2. The extension executes:

   nik dev compile <workspace-folder>

3. Compiler diagnostics are mapped directly to your source files using the $niksphere-compiler problem matcher.
4. Upon successful compilation, an installable package is generated in the project's .nikpackages/ directory:

   .nikpackages/com.example.customer-1.0.0.nikapp

4. Publishing to the Active Environment (Ctrl+F5)

The fastest way to test changes is the single-step Publish App workflow:

1. Click $(cloud-upload) Publish App in the status bar, or press Ctrl+F5 (macOS: Cmd+F5).
2. The extension resolves the Active Environment and executes:

   nik dev publish <workspace-folder> -s <active-environment-url>

3. The publish process performs the following actions:
   • Compiles and validates all entities, pages, and Pascal units.
   • Packages the app into .nikpackages/<app-id>-<version>.nikapp.
   • Sends the package via POST /admin/apps/publish to the target engine.
   • Upgrades and installs the app schema and metadata in the engine database.
   • Refreshes the Apps view in the sidebar upon completion.

5. Selecting the Active Environment

By default, the extension targets http://localhost:3000. To publish to a different environment:

1. Open the Niksphere view in the Activity Bar.
2. In the Environments section, click on the desired target server (or right-click and select Use Environment).
3. The selected environment is now active for all subsequent compile, publish, and inspect actions.

TIP

You can also persist a default active environment in .vscode/settings.json:

{
  "niksphere.environments": [
    { "name": "Staging", "url": "https://staging.internal.example.com", "active": true }
  ]
}

6. Troubleshooting

CLI Not Found Error

• If VS Code displays Niksphere CLI (nik) could not be found, verify that nik is in your PATH.
• Alternatively, set the absolute path in VS Code Settings:

  {
    "niksphere.cliPath": "C:\\Program Files\\Niksphere\\bin\\nik.exe"
  }

Authentication Errors (401 Unauthorized)

• If publishing fails with an authentication error, right-click the target environment in the sidebar and choose Login, or authenticate in the terminal:

  nik env auth login <engine-url>