These docs are for v1.0. Click to read the latest docs for v1.2.

Getting started with the Extension API

Creating and testing shape libraries through the Extension API requires using commands from Lucid's CLI and editing files directly. To start, you can create a shape library using the following command in an existing package:

npx lucid-package create-shape-library <name>

This will create a shape library with one custom shape (a simple rectangle) and a default library.manifest.

📘

For creating a library just from images, see create-image-shape-library.

File organization

In a new shape library directory, you will have the following structure:

> my-library
    > images
        └── ...
    > shapes
        └── first.shape
    └── library.manifest
{
    "properties": [],
    "geometry": [
        {
            "type": "rect"
        }
    ]
}
  • The images folder is where you can store images to be referenced in your .shape files.

  • The shapes folder is where your .shape files will be stored, which house shape definitions.

    • first.shape is a boilerplate shape file that contains a basic shape definition.
  • The library.manifest file lists the name of the shape library and which shapes are included in the shape library. It lists its shapes through shape entries. Take note that each shape entry must reference a valid .shape file (e.g. shape: shape1 for the file /shapes/shape1.shape) and any .shape file that is not referencd by a shape entry won't show up in your library.

Library manifest

{
    "name": "Test Library",
    "shapes": [
        {
            "shape": "first",
            "name": "Test Shape",
            "defaults": {
                "fillColor": "#ff0000",
                "strokeColor": "#00ffff",
                "strokeWidth": 3,
                "width": 300,
                "height": 300
            }
        }
    ]
}
PropertyTypeDescription
namestring or TranslatableStringThe name of the shape library
shapesShapeEntry[]The list of shapes in this shape library. Only shapes in this list are shown

ShapeEntry

PropertyTypeDescription
shapestringThe basename for the shape file, found in /shapes/shapeId.shape
keystring (optional)If specified, can be used to differentiate between multiple shape entries with the same shape value when calling EditorClient.getCustomShapeDefinition
namestring or TranslatableStringThe name displayed for this shape in the shape library
defaultsShapeDefaultsDefault block properties, like width, height, fill, etc.
properties{string:string} (optional)Default values for custom shape data, defined in the shape definition

ShapeDefaults

PropertyTypeDescription
widthnumberThe initial shape width
heightnumberThe initial shape height
roundingnumber (optional)The initial shape rounding
fillColornumber (optional)The initial fill color for the shape
strokeColornumber (optional)The initial line color for the shape
strokeWidthnumber (optional)The initial line width for the shape
opacitynumber (optional)The initial opacity for the shape
rotationnumber (optional)The initial rotation for the shape
aspectRationumber (optional)Fixed aspect ratio. See also locked
linkstring (optional)Starting url link on the shape

TranslatableString

PropertyTypeDescription
defaultstringThe fallback value to display if the i18n value is not found
i18nstringThe i18n key from the i18n files

Testing

Any time you are running npx lucid-package test-editor-extension, all shape libraries in the package will be automatically displayed in the Lucidchart toolbox. You can also use npx lucid-package test-shape-libraries to test your shape libraries without needing any editor extension to exist.

Custom shapes are kept up to date as you make code changes to the shape definitions. You do not need to reload the page to see your changes, but note that shapes on the canvas will not be updated.

📘

This does not happen for released extensions. It is only a convenience while developing locally.