Release Log for Plugin Developers - 2025-06-29
Reference: enhance(plugins): block property related apis (#11953)
Block Property API Enhancements
Major Improvements
-
Reliable Property Namespacing
- Plugin-defined block properties are now strictly namespaced (
plugin.property.<your_plugin>.<property>
orplugin.property._api.<property>
if plugin ID is missing). - This prevents property collisions across plugins and aligns with best practices for multi-plugin environments.
- Plugin-defined block properties are now strictly namespaced (
-
Stricter Property Name Sanitization
- Property keys are now lowercased, whitespace-trimmed, and stripped of leading symbols.
- Internal/built-in property names (
logseq.*
,block.*
) are protected and cannot be overridden or shadowed by plugins.
-
Full CRUD Support for Plugin Block Properties
- All property APIs (
upsertBlockProperty
,removeBlockProperty
,getBlockProperty
,getBlockProperties
) are now robust for both file-based and DB-based graphs. - Plugin properties are safely created, read, updated, and removed with correct scoping.
- All property APIs (
-
Property Schema Management
- Plugin APIs allow you to define property type (
default
,number
,node
,date
,checkbox
,url
, etc.) and cardinality (one
vsmany
). - Type inference and enforcement is improved; illegal type/cardinality changes will throw descriptive errors.
- Plugin APIs allow you to define property type (
-
Complex Property Type Support
- You can now store arrays, objects, booleans, and numbers as block properties.
- Plugin properties are automatically serialized/deserialized as JSON when needed.
-
Stronger TypeScript Typings
- The plugin SDK’s TypeScript types have been updated to reflect all new property types and method signatures.
Testing & Debugging
- Expanded E2E Test Coverage
- Property-related plugin APIs are now covered by robust E2E tests.
- Tests cover property CRUD, schema validation, and edge cases for both DB and file-based graphs.
Dependency Update
- Added
jsonista
Clojure dependency- Ensures reliable round-tripping of property values in tests and plugin code.
Migration & Compatibility Notes
- If your plugin was previously using non-namespaced property keys, update your usage to the new namespaced format to avoid conflicts and ensure forward compatibility.
- Always use the provided API helpers for property CRUD, and avoid manipulating property keys directly.
- Test your plugin on both file-based and database-backed graphs to verify property persistence and behavior.
Example: Plugin Property Usage
// Upsert a property (namespaced automatically)
await logseq.Editor.upsertBlockProperty(blockUuid, "myCustomProp", { foo: "bar", count: 3 });
// Get all block properties (namespaced keys)
const props = await logseq.Editor.getBlockProperties(blockUuid);
// Remove a property
await logseq.Editor.removeBlockProperty(blockUuid, "myCustomProp");
These changes make Logseq plugins more robust, isolated, and future-proof. Happy hacking!