The core of Local's Add-on API is the Hooks API. This API was heavily inspired by WordPress' Plugin API. If you've written WordPress themes or plugins before, you should feel right at home!

Content Hooks

Filters

Actions

Available Actions

Example

hooks.addAction('siteAdded', function (site) {
	console.log('New site added!', site);
});

Add-ons extend Local in one of two ways:

• Events that are registered with the Local UI are added to the "Renderer" entry point.

• Events that don't register with the Local UI are added to the "Main" entry point.

​Renderer entry point​

The renderer process is what runs inside Local's main window. This is where you'll add buttons, forms, and any other user interface elements.

Most Add-ons will exclusively use the renderer process entry point for the sake of simplicity.

To use this entry point, ensure that a renderer property is defined within the package.json file, which points to the compiled Javascript file.

Local passes a context object to the exported function, which allows you to leverage existing tools that are already shipped with Local.

​Main entry point​

The main process allows you to register and hook into Local functionality that doesn't rely on the Local UI. By tapping into the main process, you can run processes even when the window is closed but Local is still running.

To use this entry point, ensure that a main property is defined within the packge.json file, which points to the compiled Javascript file.

Local passes a context object to the exported function, which allows you to leverage existing tools that are already shipped with Local.

Curious to see how this works in practice? Check out the Add-ons in the . Each add-on has a link to the Repository where you can review the code or clone it locally to pick apart and improve!

If you need to add UI components to your Local Add-on, we recommend using the @getflywheel/local-components package which is available on npm.

To see what components are available in local-components, check out our styleguide.

Local is powered by Electron/Node.js. This means all Add-ons interface with Local using a simple JavaScript API.

With that in mind, don't think Local Add-ons can only be JavaScript. Node.js provides robust APIs such as which enable executing outside binaries and shell scripts.

Also, thanks to the vast ecosystem of modern JavaScript, you can write your Local Add-on in any language that transpiles to ES5, such as ES6, ES7, or .

You can get up and running with your new add-on quickly and easily with the . It is super simple to set up, and can help you start creating your new add-on in no time! It automatically sets up a bare-bones add-on in Local, and shows some helpful tips and examples (many of which are detailed in the following sections) to jumpstart your add-on development.

context.environment

Includes the following properties:

• appPath: Path to running Local by Flywheel.app

• userHome: Path to current user home directory

• phpVersion: Available PHP versions in Local

• version: Local version

• dockerPath: Path to Docker binary in Local by Flywheel.app

• userDataPath: Path to Local's user data folder. On macOS this defaults to ~/Library/Application Support/Local by Flywheel

context.hooks

Use context.hooks to run actions at certain times. Hooks are especially useful when adding in element with context.React.

context.electron

Exposes Electron API. The available methods and classes will differ based on whether or not this is ran from the main process or renderer process.

With the Electron API you can create dialogs, open new windows, and more.

context.fileSystem

​fs-extra npm package, which extends the native fs API in Node.js.

context.fileSystemJetpack

​fs-jetpack npm package. Some may prefer it over the native fs API in Node.js.

context.notifier

​node-notifier npm package. The main method in this class is notify.

Example

context.notifier.notify({  
    title: 'Notification Title',  
    message: 'This is an example notification message.',
});

context.process

Node.js process object.

context.React

Renderer Only

context.React required to use JSX in your renderer entry point. You can also use context.React to access React's Top-Level API.

context.ReactRouter

• Link - https://reactrouter.com/web/api/Link

• NavLink - https://reactrouter.com/web/api/NavLink

• Route - https://reactrouter.com/web/api/Route

• Router - https://reactrouter.com/web/api/Router

Deprecated

The following contexts have been deprecated in the most recent versions of Local.

context.request

​request npm package, which makes it very easy to send HTTP/HTTPS requests.

The request package was deprecated on Feb 11th 2020, and removed from Local in the [v8.0.0](https://community.localwp.com/t/local-beta-8-0-0/39385) release.

context.docker

Use context.docker to run Docker commands.

Example

context.docker(`start ${container}`).then(stdout => {    
    //Success
}).catch(({stdout, stderr}) => {    
    //Something bad happened
});

site

Plain JavaScript object containing information about the selected site.

Example:

{
    "id": "BeyQOnaNS",
    "localVersion": "3.1.2",
    "container": "c61d2aba97ca2306edd42f03275dae0bbda570abe8d93e9ad2ba2a9a93bea895",
    "phpVersion": "7.2.9",
    "webServer": "nginx",
    "mysqlVersion": "5.7",
    "multiSite": null,
    "mysql": {
      "database": "local",
      "user": "root",
      "password": "root"
    },
    "ports": {
      "HTTP": 4049,
      "HTTPS": 4050,
      "MYSQL": 4051,
      "MAILCATCHER": 4052
    },
    "flywheelConnect": "flywheel-site-hash",
    "environment": "flywheel",
    "workspace": null,
    "name": "Example Site",
    "path": "/Users/username/Local Sites/example-site",
    "domain": "example-site.local",
    "environmentVersion": "1.3.2",
    "sslSHA1": "14f0808d7312bf4031ee198aec75cbd20b8aee2d"
  }

siteStatus

String containing one of the following values:

Common statuses

• adding

• cloning

• copying

• deleting

• exporting

• exporting-db

• halted

• provisioning

• running

• saving

• stopping

Error statuses

• container-missing

• provisioning-error

• wordpress-install-error

Pulling

• pulling-downloading-backup

• pulling-importing-backup

• pulling-requesting-backup

Pushing

• pushing-packing

• pushing-processing

• pushing-uploading

Available Content Hooks

Examples

Adding a React Component

Adding a Route

Environment Content Hooks

The following Content Hooks are meant to be used by Environments such as the Preferred and Custom Environment.

ENV_ID and ENV_VERSION are in the hook name to allow for multiple Environments to be loaded at the same time and to cut down on the number of conditionals required.

Available Filters

Filter Name

appMenu

Description

Allows you to add or modify items in the main app menu (top bar menu)

Callback Function Parameters

• macOS Menu Template

• Current Platform provided by process.platform

function(menu: MenuTemplate[], platform: string): MenuTemplate[];

_____________________________________________________________

Filter Name

siteInfoMoreMenu

Description

Allows you to add menu items to the Site Info More menu inside of a single site view.

Callback Function Parameters

• menuItems

• currentSite

function(menuItems: SiteInfoMoreMenuItem[], site: Site): SiteInfoMoreMenuItem[];

Example

hooks.addFilter('siteInfoMoreMenu', function (menu, site) {

	menu.push({
		label: 'Volumes',
		enabled: !this.context.router.isActive(`/site-info/${site.id}/volumes`),
		click: () => {
			context.events.send('goToRoute', `/site-info/${site.id}/volumes`);
		},
	});

	return menu;

});

_____________________________________________________________

Filter Name

preferencesMenuItems

Description

Add-ons have the ability to add items to Local's preferences section by using the preferencesMenuItems filter hook. This filter will add a new item to the left hand column of all Preferences views and allow add-ons to add their own content section.

An AddonSettingsItem object is given to Local via the preferencesMenuItems hook (see usage examples below). This can then render an array of PreferencesSection's or any React component. The latter is provided mainly as an escape hatch in the case that an add-on needs more flexibility. Each PreferencesSection then provides an optional header and a single or array of MenuContentRowItem(s).

Props passed to <Row /> or <Override /> components

{
	// React Router props (types are not accurately documented here and developers should reference the React Router documentation for more details)
	history: any;
	location: any;
	match: any;
	params: any;

	// controls whether or not the "apply" button (rendered by Local) is enabled (clickable) or disabled (not clickable)
	setApplyButtonDisabled: (isDisabled: boolean) => void;

	// various other props may be passed via Local but are not an offically supported component of this API as of the time of writing
}

Callback Function Parameters

• preferencesMenu

function(preferencesItem: PreferencesItem[]): PreferencesItem[];

Examples

"Standard" example passing in sections and sub-headers

const preferenceItem: AddonSettingsItem = {
	path: 'image-optimizer',
	displayName: 'Image Optimizer',
	sections: [
		{
			// subHeader is optional and if omitted, no subHeader will be rendered
			subHeader: 'header 1',
			rows: [
				{
					// this defines what string will be rendered in the left hand "column" of a row
					name: 'line 1',
					// this defines what will be rendered in the right hand "column" of a row. It can be any React component.
					component: Preferences,
				},
				// ...add some more rows if you want
			],
		},
		// ...add some more sections if you want
	],
	onApply: () => {
		console.log('changes applied!')
	},
	componentProps: {
		// This optional object can be any arbitrary props to get passed to your row components (or Override component)
	},
};

hooks.addFilter(
	'preferencesMenuItems',
	(menu) => {
		menu.push(preferenceItem);

		// remember to return the menu array here! If you don't Local won't be able to render your Preference item
		return menu;
	}
);

Overriding Sections with a single React Component (allows you to render arbitrary things in the "content area")

const preferenceItem = {
	path: 'image-optimizer',
	displayName: 'Image Optimizer',
	// this can also just be any old React component. It will be rendered in the Preferences content area
	sections: (props) => <div>{props.title}<div/>,
	onApply: () => {
		console.log('changes applied!')
	},
	componentProps: {
		/* Arbitrary props that will get passed to your row components or section override component. */
		/* here we are passing it "title" which will get passed to the "sections" component */
		title: 'Preferences Title',
	},
}

hooks.addFilter(
	'preferencesMenuItems',
	(menu) => {
		menu.push(preferenceItem);
 
		return menu;
	};
);

Environment Filters