Flaxon VS Code extension

The Flaxon extension adds project scaffolding, route discovery, Python completions, hover help, diagnostics, snippets, CodeLens, and run/debug commands to Visual Studio Code. The Python extension and Pylance remain responsible for general Python language support.

Extension source | VS Code Marketplace

Requirements

• Visual Studio Code 1.74 or newer.
• Python 3.11 or newer.
• The Microsoft Python extension; Pylance is recommended.
• Flaxon installed in the same virtual environment used by VS Code.

Install from VS Code

1. Open Extensions with Ctrl+Shift+X on Windows/Linux or Cmd+Shift+X on macOS.
2. Search for Flaxon, select the Flaxon extension, and choose Install.
3. Reload VS Code if prompted.
4. Open a trusted folder containing app.py, main.py, run.py, or flaxon.py.

Install from a VSIX

code --install-extension flaxon-vscode-0.1.5.vsix

You can also choose Install from VSIX... from the Extensions ... menu. Prefer the exact VSIX filename from the release because publisher identifiers and filenames may vary by release.

Create a project

Open the Command Palette with Ctrl+Shift+P or Cmd+Shift+P, then run Flaxon: Create Project. Manual setup:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install "flaxon[standard]"
code .

On macOS/Linux activate with source .venv/bin/activate. Create app.py:

from flaxon import Flaxon

app = Flaxon("my-api")

@app.get("/api/health")
async def health():
    return {"status": "healthy"}

Save the file. The extension activates on Python files and indexes supported Flaxon decorators.

Workspace settings

Create .vscode/settings.json:

{
  "flaxon.pythonPath": ".venv\\Scripts\\python",
  "flaxon.entryPoint": "app:app",
  "flaxon.debug.reload": true,
  "flaxon.enableRouteExplorer": true,
  "flaxon.enableCodeLens": true,
  "flaxon.enableDiagnostics": true,
  "flaxon.enableCompletions": true,
  "flaxon.snippets.enable": true,
  "flaxon.trace.server": "off"
}

Use .venv/bin/python for macOS/Linux. The entry point uses module:variable, such as main:app. Select the same interpreter in the Python extension.

Route Explorer

Run Flaxon: Show Routes or press Ctrl+Shift+R. The Flaxon Routes view groups recognized HTTP and WebSocket routes by file. Select a route to jump to its handler. Save files after editing so the index can refresh.

@app.get("/users")
async def users():
    return {"users": []}

@app.post("/users")
async def create_user():
    return {"created": True}

@app.websocket("/ws/chat")
async def chat(socket):
    await socket.accept()

Completions, hover, and snippets

Type @app. for route decorators, fields. for validation fields, or request. for request APIs. Hover supported symbols for examples. Available Python snippets include:

CodeLens and diagnostics

CodeLens can show run, debug, and reference actions above recognized routes. Diagnostics flag common mistakes such as missing Flaxon imports, missing application objects, non-async handlers, missing returns, missing WebSocket acceptance, and validation imports. They are editor hints, not a replacement for tests.

Run and debug

Run Flaxon: Run App or press Ctrl+Shift+F5. Equivalent CLI:

flaxon run app:app --reload

Flaxon: Debug App launches the Python debugger. A manual .vscode/launch.json entry is:

{
  "version": "0.2.0",
  "configurations": [{
    "name": "Flaxon: Debug App",
    "type": "debugpy",
    "request": "launch",
    "module": "flaxon",
    "args": ["run", "app:app"],
    "console": "integratedTerminal",
    "justMyCode": true
  }]
}

Generate code

• Flaxon: Generate Route asks for path, method, and optional name.
• Flaxon: Generate Schema creates a validation schema and fields.
• Flaxon: Open Documentation opens the Flaxon documentation.
• Flaxon: Restart Language Server reloads indexing, completions, hover, diagnostics, definitions, and references.

Teloce and .vel

The Flaxon extension supports Python. Teloce-Py is the separate compiler for .vel components. Use Teloce tooling for .vel syntax and run its CLI from the integrated terminal:

python -m pip install teloce-py
teloce doctor --verbose
teloce dev
teloce build --out-dir dist --source-map

Flaxon serves generated JavaScript/CSS and owns the API, authentication, authorization, and persistence. See Teloce-Py documentation.

Language-server logs

Open Output with Ctrl+Shift+U, select Flaxon, and temporarily enable:

{ "flaxon.trace.server": "verbose" }

Set tracing back to off after diagnosis.

Testing and extension development

python -m pytest
flaxon doctor app:app
flaxon routes app:app

# From the Flaxon VS Code extension repository:
npm install
npm test
npm run package

The extension test workflow compiles TypeScript, runs lint and parser/LSP tests, and verifies a VSIX package. Keep project settings safe for the team and secrets in environment configuration.

Troubleshooting

Extension does not activate

Open a Python file in a trusted workspace, select the correct interpreter, install Flaxon, and reload VS Code. Check the Flaxon Output channel.

Route Explorer is empty

Save the file, confirm decorators such as @app.get, @app.post, or @app.websocket, check flaxon.entryPoint, and restart the language server.

Completions or CodeLens are missing

Enable flaxon.enableCompletions and flaxon.enableCodeLens, install Python/Pylance, save the file, and restart the language server.

Run or debug fails

Run the selected Python interpreter directly, verify the entry point imports, and compare the terminal command with flaxon run app:app --reload.

Shortcuts

Security

Use trusted workspaces. The extension is an editor tool, not an authorization boundary. Keep tokens, database URLs, signing keys, and production secrets outside source files. Review third-party VSIX files before installing them.