Extension Points

Extension points allow to consume extensions registered for a given extension point name.

An extension point consist primarily of a schema to define what attributes are supported, and using the provided react hooks and components to get the extensions, share context with their factories, and validate the resulting attributes against the schema.

Schemas

A schema defines the attributes and types expected from an extension to work correctly on a given extension point. They are created using a .graphql file and graphql-style syntax.

At minimum, a schema definition needs to have the name of the extension point and a type named Schema.

schema.cse.graphql

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    """
    Extension type
    """
    type: LinkExtension!

    """
    Label of the link
    """
    label: string!
}

schema-loader

In order to use schemas, you'll need to install the @atlassian/clientside-extensions-schema webpack loader.

From there, you will be able to import the hooks and components directly from the schema as follow:

schema.cse.graphql

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    # schema definition
}

extension-point.tsx

1
2
import { useExtensions } from './schema.cse.graphql';

// Use the hooks and components resulting from importing the schema as you need

Hooks and Components

CSE provides a set of react hooks and components to consume the extensions registered for a given extension point. These hooks and components will receive an optional context, and validate the resulting attributes against the provided schema.

You can make use of them by importing the schema directly, and the loader will make them available after building the code:

schema.cse.graphql

1
2
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    """
    Extension type
    """
    type: LinkExtension!

    """
    Label of the link
    """
    label: string!

    """
    URL of the link
    """
    url: string!
}

extension-point.tsx

1
2
import React from "react";
import { useExtensions } from "./schema.cse.graphql";

const ExampleExtensionPoint = ({ context }) => {
    const extensions = useExtensions(context);

    return (
        <>
            {extensions.map(({attributes}) => <a href={attributes.url}>{attributes.label}</a>}
        </>
    )
}

export default ExampleExtensionPoint;

Extension Handlers

Client-side Extensions comes with a set of default extension types, each requiring their own API to work correctly.

Some of them are very simple, but others require a large API that can be difficult to provide on your own, so CSE provides default handlers that help you render extensions with Atlaskit components.