Skip to main content

Plugin guide

Plugins allow you to extend FreeSewing with new features and functionality. A FreeSewing plugin can extend FreeSewing in 3 different ways:

  • It can provide macros, which are a way to automate a number of steps into a single command.
  • It can hook into the pattern, which allows you to manipulate the pattern or interact with it at various stages of it's lifecycle.
  • It can provide store methods, which allows you to add new ways to handle data in the pattern, including providing a custom logger.

We have a list of plugins that we maintain, but if you can't find what you're looking for, you can write your own plugin.

If you plan on doing that or if you would like to understand how plugins work, this guide is for you.

Plugin structure​

A FreeSewing plugin is a plain object with the following structure:

Object plugin = {
  String name,
  String version,
  Object hooks,
  Object macros,
  Array store,
}

A plugin must have the name and version properties. The other properties are optional, and they map to the three different functionalities macros can provide:

  • hooks: Holds an object with lifecycle hooks the plugin wants to hook into
  • macros: Holds and object with macros the plugin provides
  • store: Holds and Array with store methods the plugin provides.

Click on the links above for more details on the structure of these properties.

Lifecycle hook methods​

FreeSewing plugins can provide hooks, which is a way to hook into the pattern's lifecycle.

Signature​

To provide one or more hooks, your plugin should have a hooks property that is an object where the keys are the lifecycle hook name and the value holds a method. When the lifecycle hook is triggered, your method will be called.

const myPlugin = {
  name: 'example',
  version: '0.0.1',
  hooks: {
    hookName: function (obj, data = {}) {
    }
  }
}

If you want to attach multiple methods to the same lifecycle hook, you can pass them as an array:

const myPlugin = {
  name: 'example',
  version: '0.0.1',
  hooks: {
    hookName: [
      function one (obj, data = {}) { },
      function two (obj, data = {}) { }
    ]
  }
}

Arguments​

All lifecycle methods will receive two parameters:

  • An object relevant to the lifecycle hook. See the hooks API reference for details.
  • Data passed when the hook was registered (optional)

Notes​

Refer to the hooks API reference for a list of all available lifecycle hooks.

Macro methods​

FreeSewing plugins can provide macros, which is a way to automate multiple steps into a single command.

Signature​

To provide one or more macros, your plugin should have a macros property that is an object where the keys are the macro name, and the value holds a method to run when the macro is executed.

const myPlugin = {
  name: 'example',
  version: '0.0.1',
  macros: {
    example: function(so, { log }) {
      log.info('Running the example macro')
    }
  }
}

Arguments​

All macros receive two arguments:

  • so: A plain object holding configuration object passed to the macro
  • props: The same object as passed to the Part.draft() method that you can destructure
Macros take only 1 argument

When writing a macro, keep in mind that all information that needs to be passed to a macro needs to be contained in a single argument.

Typically, you use a single plain object to configure the macro.

Return value​

Macros do not need to return anything. If they do, it will be ignored.

Store methods​

FreeSewing plugins can provide store methods, which facilitate data handling within a pattern.

Signature​

To provide one or more store methods, your plugin should have a store property that is an array where each member is itself an array with two members:

  • The first member holds the key to attach the method to (in dot notation)
  • The second member holds the method to attach
const myPlugin = {
  name: 'example',
  version: '0.0.1',
  store: [
    [
      'log.panic',
      function(store, ...params) {
        store.setIfUnset('logs.panic', new Array())
        store.push(...params)
      }
    ]
  }
}

Arguments​

All store methods receive at least two arguments:

  • store: The store object itself
  • ...params: All additional plugins that were passed to the store method

Overwriting store methods​

You are allowed to overwrite existing store methods. As it happens, this is how you should implement a custom logging solution, by overwriting the logging methods under the store's log key,

However, the following store methods cannot be overwritten:

  • extend()
  • get()
  • push()
  • set()
  • setIfUnset()
  • unset()

Return value​

Store methods do not need to return anything. If they do, it will be ignored.

Loading plugins​

Plugins can be loaded at build time and added to the design. Or, they can be added at run time and added to an instantiated pattern.

To load a plugin at build time, it should be added to the plugins key of the part configuration.

To load a plugin at run time, it should be loaded with a call to Pattern.use().

Please refer to the relevant documentation for more details.