Release Log for Plugin Developers

Announcements
1

Release Log for Plugin Developers - 2025-06-29

Reference: enhance(plugins): block property related apis (#11953)

Block Property API Enhancements

:rocket: Major Improvements

  • Reliable Property Namespacing

    • Plugin-defined block properties are now strictly namespaced (plugin.property.<your_plugin>.<property> or plugin.property._api.<property> if plugin ID is missing).
    • This prevents property collisions across plugins and aligns with best practices for multi-plugin environments.

  • 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.

  • Property Schema Management

    • Plugin APIs allow you to define property type (default, number, node, date, checkbox, url, etc.) and cardinality (one vs many).
    • Type inference and enforcement is improved; illegal type/cardinality changes will throw descriptive errors.

  • 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.

:test_tube: 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.

:package: Dependency Update

  • Added jsonista Clojure dependency
    • Ensures reliable round-tripping of property values in tests and plugin code.

:warning: 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!

2 Likes