The Assette VS Code Extension enables efficient local development and management of Assette content components directly within the Visual Studio Code (VS Code) environment. It is designed to support block developers, data engineers, and technical users in creating, editing, and maintaining content components like data blocks, templates, and related metadata.
This article provides a comprehensive overview of all key features available in the Assette VS Code Extension.
Extension Installation and Setup #
The extension can be installed via VSIX file for controlled distribution or through the VS Code Marketplace (in production environments). It supports configuration for different environments, including development, staging, and production.
See: Installing the Assette Block Editor VS Code Extension
Authentication #
The extension supports secure Single Sign-On (SSO) authentication. Once installed:
- Users can sign in using their organizational credentials via the “Sign In” link in the sidebar.
- On successful login, all features including upload and download operations are unlocked.
See: Signing Into the Assette VS Code Extension
Workspace Awareness #
The extension operates within the context of an open workspace folder in VS Code. All file operations are scoped to this workspace, including downloads, uploads, and metadata handling.
- If no folder is open, the extension will notify the user: “No workspace folder is open.”
See: Error and Status Messages Reference
Download Capabilities #
Users can retrieve content components from the Assette platform into their local environment for editing and review.
Download Options: #
- Download a Single Block
- Download All Blocks
- Download All Types of Blocks
- Download Block by Name
Downloaded files include code, configuration files, and metadata. ZIP packages are extracted automatically, and errors are clearly reported if the process fails.
Upload Capabilities #
Users can publish content changes from their local environment to the Assette platform using several upload options:
Upload Options: #
- Upload a Single File
Upload individual block or configuration files. - Upload All Blocks in Folder
Upload all valid files within a folder, respecting folder structure and metadata. - Upload Modified Blocks
Uploads only those blocks that have been detected as modified based on timestamps and sync metadata. - Upload Template Files
Uploads template data for Smart Docs or Web Docs, including required metadata.
Each upload function includes:
- Retry logic with user feedback
- Validation for required metadata
- Folder structure verification
- Summary reporting after upload completion
File Status and Change Detection #
The extension automatically scans the workspace to detect modified files using metadata such as last sync time and modification timestamps.
- Displays whether a file has been marked as modified
- Lists how many files are ready for upload
- Errors or warnings shown for missing metadata or unrecognized files
Error Handling and Status Messages #
All major operations (authentication, file system, uploads, downloads) include clearly defined status and error messages. These help users understand:
- Why a task failed
- Whether it will retry
- What action is required to resolve the issue
Hover tooltips, log entries, and retry counters provide additional context during failures.
See: Error and Status Messages Reference
Metadata Awareness #
The extension supports structured metadata handling for Assette blocks and templates:
- Identifies missing or incomplete metadata
- Validates file and folder labels
- Allows users to proceed without metadata where optional
Retry and Recovery Mechanism #
Built-in retry logic helps ensure operations are resilient to transient errors such as network interruptions or temporary API failures.
- Retry attempts are displayed with progress count
- Final failure messages provide actionable detail
Operational Warnings #
The extension alerts users when they are about to perform potentially disruptive actions, such as:
- Uploading all blocks in a folder
- Uploading without metadata
- Selecting an unsupported folder structure
These warnings are designed to minimize accidental overwrites or structural conflicts.
Limitations #
The VS Code Extension does not include visibility into where a component is used (e.g., templates referencing a block). To view component relationships, users must use X-Ray in the Assette web application.
See: How to Find Where a Component is Used in the VS Code Extension