Netlify 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 Hooks

The Netlify SDK can be used to generate build hooks. 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 build hook. 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 Netlify build 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 Netlify 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.

Client

One of the arguments passed to the handler function is a client object, which is found within the context object. This client provides friendly interfaces for interacting with the Netlify API.

Additionally, you are able to read and modify integration state, relating to the current site or team. The following methods are available:

• getSiteIntegration()
• getTeamIntegration()
• enableSiteIntegration()
• enableTeamIntegration()
• updateSiteIntegration()
• updateTeamIntegration()

Custom Integration UI

You can create a custom UI for your integration by importing the NetlifyIntegration class. Head to the Integration UI documentation for more information on:

• adding elements for basic UI, forms, text, identity, and more
• making the UI interactive, and
• accessing information about the site and user

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.