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:

Shell

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:

inline:bash

> my-library
    > images
        └── ...
    > shapes
        └── first.shape
    └── library.manifest

first.shape

{
    "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

library.manifest

{
    "name": "Test Library",
    "shapes": [
        {
            "shape": "first",
            "name": "Test Shape",
            "defaults": {
                "fillColor": "#ff0000",
                "strokeColor": "#00ffff",
                "strokeWidth": 3,
                "width": 300,
                "height": 300
            }
        }
    ]
}

Property	Type	Description
name	string or TranslatableString	The name of the shape library
shapes	ShapeEntry[]	The list of shapes in this shape library. Only shapes in this list are shown

ShapeEntry

Property	Type	Description
shape	string	The basename for the shape file, found in /shapes/shapeId.shape
key	string (optional)	If specified, can be used to differentiate between multiple shape entries with the same shape value when calling EditorClient.getCustomShapeDefinition
name	string or TranslatableString	The name displayed for this shape in the shape library
defaults	ShapeDefaults	Default block properties, like width, height, fill, etc.
properties	{string:string} (optional)	Default values for custom shape data, defined in the shape definition

ShapeDefaults

Property	Type	Description
width	number	The initial shape width
height	number	The initial shape height
rounding	number (optional)	The initial shape rounding
fillColor	number (optional)	The initial fill color for the shape
strokeColor	number (optional)	The initial line color for the shape
strokeWidth	number (optional)	The initial line width for the shape
opacity	number (optional)	The initial opacity for the shape
rotation	number (optional)	The initial rotation for the shape
aspectRatio	number (optional)	Fixed aspect ratio. See also locked
link	string (optional)	Starting url link on the shape

TranslatableString

Property	Type	Description
default	string	The fallback value to display if the i18n value is not found
i18n	string	The 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.