AppForge

Appwrite-native Developer Cockpit for VS Code

Manage Appwrite Projects, Databases, Collections, Documents, Functions, Storage, Logs, Diagnostics, and Self-Hosted Instances directly from VS Code.

---

🚀 Why AppForge?

Stop switching between VS Code and the Appwrite Console.

AppForge brings Appwrite management directly into your editor with a dedicated explorer, diagnostics suite, structured logging, telemetry, and project management workflows.

Overview

AppForge removes the friction of bouncing between VS Code and the Appwrite console for everyday backend tasks. It is designed for developers who manage multiple Appwrite projects, need fast context switching, and want reliable visibility into what the extension is doing when data looks wrong.

It solves the problems that usually show up in real Appwrite workflows:

• Switching between tools just to inspect projects, databases, or functions
• Losing confidence in backend state when async refreshes race each other
• Debugging empty or inconsistent results without enough logging
• Managing multiple projects with unsafe shared client state
• Repeating setup work every time you return to the console

Core Features

Multi-Project Management

• Store multiple Appwrite projects securely in VS Code workspace state and SecretStorage
• Add, remove, and switch projects from the sidebar or command palette
• Keep project metadata isolated by project ID
• Auto-load the active project on extension activation
• Status bar indicator for quick project identification

Database Explorer

• Hierarchical tree view of databases, collections, and documents
• Lazy-load documents for responsive navigation (first 100 documents)
• Inspect collection attributes with field types
• View indexes and their configurations
• Create, update, and delete documents directly
• Collection schema browser with attribute details

Functions Explorer

• Browse all functions per project
• View deployment metadata and configurations
• Inspect function variables and settings
• Execute functions directly from the sidebar
• Deploy new function versions without leaving VS Code
• Execution history and status tracking

Storage Explorer

• Browse buckets and file contents per project
• View bucket permissions and metadata
• Inspect file details and sizes
• Upload and delete files from the UI
• File management through context menus
• Bucket-level access control inspection

TreeView Resource Explorer

• Unified sidebar explorer for all Appwrite resources
• Expand resources lazily for responsive navigation
• Preserve expansion state across refreshes
• Use context menus for quick actions on all resource types
• Color-coded tree items for resource types

Logs Viewer

• Centralized WebView panel for operation logs
• Raw REST and SDK response inspection
• Structured logging with success/warning/error/debug levels
• Timing information for async operations
• Diagnostic traces for troubleshooting
• Export logs for support workflows

Appwrite Integration

• Connect to Appwrite Cloud or self-hosted Appwrite instances
• Use Appwrite API keys for backend operations
• Validate connections before saving a project
• Run database, function, and storage workflows from within VS Code
• Support for multiple Appwrite versions

Project Switching

• Switch context instantly from the sidebar or status bar
• Avoid manual reconfiguration when moving between environments
• Keep each project node independent and deterministic
• Reduce stale state during fast project changes
• Status bar shows active project name

Diagnostics System

• Inspect stored project metadata and connection details
• Compare SDK responses with raw REST responses
• Troubleshoot empty database results with dedicated tooling
• Verify project and endpoint identity before chasing UI bugs
• Comprehensive runtime logging with console traces

Logging System

• Structured runtime logging through the Output Channel
• Success, warning, error, and debug events
• Timing-aware logging for async operations
• Diagnostics output designed for real support workflows
• Diagnostic traces for proof of execution: [TREE], [DATABASES], [STATUSBAR], etc.

Developer-Focused UX

• Validation-rich setup forms
• Loading indicators for long-running operations
• Confirmation dialogs for destructive actions
• Command palette integration for all major workflows
• Clear status feedback for project and backend actions

Type-Safe Architecture

• Written in strict TypeScript
• Uses Zod for configuration and input validation
• Built on VS Code extension APIs with explicit service boundaries
• Keeps project state, backend state, and UI state separated

Command Palette Integration

• AppForge: Add Project
• AppForge: Remove Project
• AppForge: Switch Project
• AppForge: Refresh Projects
• AppForge: Refresh Databases
• AppForge: Refresh Functions
• AppForge: Refresh Storage
• AppForge: Create Collection
• AppForge: Create Document
• AppForge: Delete Document
• AppForge: List Documents
• AppForge: Update Document
• AppForge: Execute Function
• AppForge: Deploy Function
• AppForge: View Logs
• AppForge: View Function Logs
• AppForge: Check Project Status
• AppForge: View Connection Info
• AppForge: Troubleshoot Empty Databases
• AppForge: Verify Appwrite Project Environment
• AppForge: Run Diagnostics

✨ What's New in v0.2.1-alpha

🌐 Self-Hosted Appwrite Support

One of the most requested fixes.

AppForge now fully supports self-hosted Appwrite deployments alongside Appwrite Cloud.

Improvements include:

• Better endpoint validation
• Database discovery fixes
• Collection loading reliability
• Improved compatibility across Appwrite versions
• Enhanced diagnostics for self-hosted instances

This resolves the issue where some self-hosted users could connect successfully but resources would not appear in the explorer.

Experimental Features:

• Function deployment via drag-and-drop (upcoming)
• Real-time document change notifications (upcoming)

This release focuses on making Appwrite resources fully visible and queryable from VS Code, with transparent logging to build confidence in multi-project workflows.

Architecture

🏗 New Architecture (v0.2.1-alpha)

AppForge now includes a modern internal architecture designed for scalability and realtime operations.

Event Bus

• Strongly typed events
• Async-safe listeners
• Debounced updates
• Event history tracking

Refresh Manager

• Intelligent refresh queue
• Scoped refreshes
• Debouncing
• Loading state tracking
• Cache invalidation

Output Channel Manager

• Structured logging
• Performance metrics
• Error tracking
• Operation timelines

Telemetry Layer

• Function execution monitoring
• API latency tracking
• Resource loading metrics
• Failure analytics

AppForge is organized around explicit boundaries so project context never depends on hidden global state.

Project-Scoped Services

Each Appwrite operation is created from project-specific inputs rather than a long-lived mutable client. That keeps database, function, and diagnostic calls tied to the project being acted on.

Appwrite Client Lifecycle

The client layer now acts as a factory for isolated SDK instances. Services are created per project and per operation, then discarded after use. That removes cross-project contamination and async race conditions caused by shared state.

Extension Structure

• src/extension.ts wires activation, services, and command registration
• src/providers/treeDataProvider.ts owns the sidebar resource explorer
• src/commands/ contains project, database, function, and diagnostics workflows
• src/views/ contains webviews and resource panels
• src/services/ contains storage and Appwrite client factories
• src/core/ contains refresh orchestration, events, and output logging
• src/types/ contains shared type definitions
• src/utils/ contains validation and parsing helpers

Diagnostics Flow

Diagnostics are designed to answer a simple question quickly: is the problem local, configuration-related, or remote?

The current flow captures:

• Stored project metadata from workspace state
• Redacted API key context
• Endpoint and project ID identity
• SDK response payloads
• Raw REST response payloads

Command System

Commands are exposed through the command palette and sidebar interactions. Each command resolves project context explicitly before creating its Appwrite service, which keeps behavior deterministic even when multiple projects are open or switching quickly.

📸 Screenshots

Project Explorer

Browse all Appwrite resources directly from VS Code.

---

Database Explorer

View databases, collections, attributes, indexes, and documents.

---

Functions Explorer

Manage deployments, executions, and environment variables.

---

Storage Explorer

Inspect buckets and files without leaving VS Code.

---

Logs Viewer

View structured logs and diagnostics.

---

Project Switching

Instantly switch between Appwrite projects.

Installation

From Source

git clone https://github.com/ArhanAnsari/appforge.git
cd appforge
npm install
npm run build

Run the Extension Host

npm run watch

Then press F5 in VS Code to launch the Extension Development Host.

Development

Common Commands

npm run check-types
npm run lint
npm run build
npm run watch

Project Structure

For a deeper layout reference, see FOLDER_STRUCTURE.md.

src/
├── commands/   # Project, database, function, and diagnostics commands
├── core/       # Event bus, refresh manager, and output channel
├── providers/  # TreeView data provider
├── services/   # Appwrite and storage services
├── types/      # Shared TypeScript definitions
├── utils/      # Validation and parsing helpers
└── views/      # Webview panels

Quality Gates

• Strict TypeScript compilation
• ESLint validation
• Explicit service boundaries
• Structured runtime diagnostics
• Secure credential storage

Roadmap

AppForge v0.2.0-alpha completes the core resource exploration surface for Databases, Functions, and Storage. The roadmap beyond v0.2.0 is focused on operational confidence and multi-project automation.

v0.2.1-alpha (Stabilization & Logs)

• Logs Viewer feature completion with filtering and export
• Function execution logs viewer
• Improved error messages for common failure modes
• Performance optimization for large databases and function counts
• API response caching for frequently-accessed resources

v0.3.0-alpha (Operations & Automation)

• Search and filter across databases, functions, and storage
• Bulk operations: delete multiple documents, manage permissions
• Resource tagging and favorite management
• Git-aware function deployment (deploy from current branch)
• Environment variable management per project
• Function execution scheduling and monitoring

Future Roadmap

• Auth management and user administration
• Real-time monitoring for logs and backend events
• AI-assisted developer tooling and smart diagnostics
• Appwrite Cloud region and environment diagnostics
• Direct resource editing for supported Appwrite entities
• Deployment workflows for functions, databases, and schemas
• Team collaboration features for shared workspaces
• Custom resource templates and scaffolding

Contributing

Contributions are welcome.

Please keep changes focused, typed, and consistent with the existing architecture:

1. Fork the repository and create a feature branch.
2. Preserve strict TypeScript compatibility.
3. Prefer explicit project-scoped logic over shared mutable state.
4. Add or update diagnostics when fixing backend integration issues.
5. Run typecheck and lint before opening a pull request.
6. Keep the README and docs aligned with user-facing changes.

If you are proposing a larger workflow or architecture change, include the reasoning and validation path in the pull request description.

Documentation

• Release notes: CHANGELOG.md
• v0.2.1-alpha release report: RELEASE_REPORT_v0.2.1-alpha.md
• Folder layout reference: FOLDER_STRUCTURE.md

Troubleshooting

Activation & Setup

• Extension does not activate: confirm VS Code ^1.120.0 or newer and reload the window.
• Projects do not appear in sidebar: verify the workspace contains saved AppForge project state.

Projects & Connection

• Connection test fails: check the endpoint, project ID, and API key.
• Project switching looks inconsistent: confirm the project ID in the sidebar matches the project ID stored in AppForge.
• Status bar does not show project name: enable LEFT alignment in status bar settings and check the Output Channel for diagnostics.

Resource Exploration

• Database explorer is empty: run AppForge: Verify Appwrite Project Environment and compare the raw REST output with the Appwrite console.
• Collections do not load: check that the selected database is accessible with the stored API key.
• Documents appear truncated: document list is limited to first 100 for performance; use the Appwrite console for full browsing.

Functions & Storage

• Functions explorer shows no deployments: verify the function is deployed via the Appwrite console first.
• Storage buckets are not visible: check bucket permissions and that files are accessible with the current API key.

Diagnostics & Logging

• No logs appear in the Logs Viewer: check the Output Channel (View → Output → AppForge) for raw extension output.
• Diagnostic traces missing: enable debug logging in VS Code settings ("appforge.logLevel": "debug").
• API call traces not appearing: run AppForge: Run Diagnostics and check the Output Channel for [TREE], [DATABASES], and [STATUSBAR] trace logs.

Requirements

• VS Code ^1.120.0
• Node.js 18+ for development
• An Appwrite instance or Appwrite Cloud project

License

MIT License.

---

AppForge is built for Appwrite developers who want stronger tooling, clearer diagnostics, and less context switching.