integration-sdk

SDK for developing integrations on Netlify

First-time Setup

Run pnpm run demo in the root of this repo. This will install node modules for ntli/demo if needed, build the ntli package, and then run the demo code.

Features

CLI

The SDK supplies a ntli utility CLI for functionality like initialising and building integrations.

init

The output of the init command will be similar to an npm init command. Assuming you're in a folder called my-cool-integration, the output of the command will be:

{
  "name": "my-cool-integration",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Build Plugins

The integration SDK can be used to generate build plugins. In the file that is listed in the main property of your package.json, declare an instance of NetlifyIntegration and call the method addBuildHook to create the desired build hook.

const integration = new NetlifyIntegration();

integration.addBuildHook("onPreBuild", () => {
  console.log('This is my build hook')
});

The command ntli build should then be used to compile the distributable code for your plugin. The distributable code will be published to dist/build/index.js, and can be published using the publish command of your package manager of choice (e.g: npm, yarn, pnpm).

Properties and utility functions mentioned in the build plugin documentation such as netlifyConfig are available in the function argument to addBuildHooks.

integration.addBuildHook("onPreBuild", ({constants}) => {
  console.log(`My site id is ${constants.SITE_ID}`)
});

Netlify Functions

The integration SDK can be used to generate Netlify Functions needed for the operation of your integration.

These functions is where the dynamic logic of your integration should live, some examples:

• Creating an environment variable on a customer's site
• Proxying calls to your API with authentication tokens
• Storing config/metadata in jigsaw

In the file that is listed in the main property of your package.json, declare an instance of NetlifyIntegration and call the method addHandler to create the desired Netlify Function.

const integration = new NetlifyIntegration();

integration.addHandler("myCoolFunction", async (event, context) => {
  const { client } = context;
  const { site_id } = event.queryStringParameters;

  const site = await client.getSite(site_id);

  console.log(site);

  return {
    statusCode: 200,
  };
});

The command ntli build should then be used to compile the code, and will be output in the dist/site/netlify directory.

These functions will be deployed and hosted by Netlify, you do not need to deploy these once they've been built.

Note: At the moment Netlify Scheduled Functions and Netlify Background Functions are not supported.

Package assets

Any file placed in src/assets will be copied to the built .ntli directory. Files and directories beginning with . will not be copied. In dev mode (ntli dev) the assets dir will be watched and any changed file will be automatically copied again.

Since the bundled JS file removes any subdirectories and flattens the directory structure, any asset paths on disk should be constructed with the path starting from the root of src. ie. fs.readFile(path.join(__dirname, 'assets/foo/etc.txt))

Breaking changes

While this package is in Alpha, all breaking changes will be released as a minor version while backwards-compatible changes will be released as a patch version.