Why Build or Use an Integration?

Integrations are perfect for you if you want to pair ZEIT's functionality with other services or want to extend ZEIT's functionality itself.

An example of this is the Google Cloud Integration which connects projects on ZEIT to Google Cloud Platform projects where you can run Now deployments as CRON jobs through the Google Cloud Scheduler, Create and connect to MySQL/PostgreSQL databases with Google Cloud SQL, and much more that would be a lot harder without an Integration.

Many more Integrations that help users in similar ways can be created using the ZEIT Integrations API in partnership with the ZEIT API and any external service with an API.

What Makes an Integration?

Before your start building your first Integration, the following is an explanation of what an Integration is built of:

• A HTTP endpoint that receives a ZEIT API token, written in any language, called a UIHook.
• It can store data such as user configuration and tokens in the Metatdata Store.
• It can return a string of HTML, using ready-made components, as the HTTP response to build UI elements.
• It can provide an interactive UI right inside the ZEIT Dashboard.
• It supports OAuth 2.

With ZEIT Integrations you have opportunity to dramatically simplify the process of using your product for your customers.

Step 1: Project Setup

{
  "name": "my-ui-hook",
  "dependencies": {
    "@zeit/integration-utils": "latest"
  }
}

{
  "name": "my-ui-hook",
  "version": 2,
  "builds": [{ "src": "index.js", "use": "@now/node" }]
}

Step 2: Creating a UIHook

This step will detail the creation of a UIHook for a counter application. This example explains the basics for how an UIHook works.

First, create an index.js file and add the following code:

const { withUiHook } = require('@zeit/integration-utils')

let count = 0

module.exports = withUiHook(({ payload }) => {
  count += 1
  return `
    <Page>
      <P>Counter: ${count}</P>
      <Button>Count Me</Button>
    </Page>
  `
})

An example index.js file for a ZEIT Integration.

Inside the UIHook there is a variable, count. Every time the Button is clicked, the UIHook is called, thus updating the counter and providing the updated HTML as a response.

This is happening inside the ZEIT Dashboard under a configuration page for this Integration.

Step 3: Creating Your Integration

With a UIHook created, you can now create the Integration on ZEIT.

To do this, visit the Integrations Developer Console and click the Create button.

Creating an Integration using the Integrations dashboard.

Complete the form and at the end you will find two fields named:

• Redirect URL
• UI Hook URL

For now, you can leave the Redirect URL empty and add http://localhost:5005 to the UI Hook URL field.

https://zeit.co/integrations/:slug

Step 4: Add a Configuration

You can visit the Marketplace URL from the previous step and click the "Add" button to add a configuration to your installation.

Then, you can select a ZEIT account to add the configuration to:

Selecting a ZEIT account to add the configuration to.

Once added, the user will be taken to the configuration page, it will look like this:

A UIHook running inside a configuration page.

Step 5: Testing Your Integration

Now you know how to create, develop, and add a configuration for an Integration, it's time to look at how you to test your Integration and develop it locally.

With your Integration running locally using now dev, navigate to the Integrations dashboard and select a configuration for your Integration.

You should now see your Integration working exactly as it would do if deployed, nothing else is required!

Step 6: Publishing Your Integration

We recommend you create a separate Integration to deploy into production. That way you have two Integrations, one for development and one for production.

This allows you to maintain a stable version of your Integration whilst still being free to develop new features for it in a safe environment.

To deploy your UIHook into production, all it takes is one command:

Deploying a UIHook to a production environment.

The output from this command will contain the alias URL for your UIHook, you should add this to your Integration in the UI Hook URL field.

Counter

This is the same example as we created in Creating an Integration section. This Integration increments a counter when the user clicks a button.

Take a look at the code on GitHub.

An example of a Counter Integration.

Basic Form

This example shows how to accept user inputs and manage different actions. It allows the user to set two values and reset them using a form.

Take a look at the code on GitHub.

An example Integration to accept user inputs.

Using Metadata

This Integration is similar to the above example, however, in this case user inputs are kept in the metadata store provided by ZEIT Integrations.

Take a look at the code on GitHub.

An example Integration that accepts user inputs and stores them in the metadata store.

Connect with GitHub

This Integration uses GitHub OAuth support to connect and receive details about a user. You can use the same process for other providers who support OAuth.

Take a look at the code on GitHub.

An example Integration that connects to GitHub.

Recent Deployments

This Integration displays a list of recent deployments from your ZEIT account or related project. It fetches deployment data from the ZEIT API using the zeitClient utility.

Take a look at the code on GitHub.

An example Integration accessing the ZEIT API and render them.

More Examples

This is a just a set of basic examples showing the key functionalities of ZEIT Integrations. By combining all these features you can build some interesting Integrations.

Have a look at this collection of ZEIT Integrations supported by ZEIT and maintained with the community support. It contains Integrations for Google Cloud, Slack, LightHouse Benchmarks, MongoDB Atlas and many more.

Background

A UIHook accepts a set of inputs, such as a token or projectId, and sends back a string of HTML, including components, as the response.

The components are sent as a string. It's just like a HTML page but with a set of rich components we have defined and exposed for you to use.

Therefore, it is the role of the UIHook to create that HTML string. This is achieved through the use of string manipulation.

With JavaScript template literals, this is relatively straightforward. However, there are a few things to be aware of:

• Escaping prop names and values
• Escaping the content that goes into components
• No array.map() support
• Difficult to share common components across different Integrations and teams

Why Use htm

Using htm greatly simplifies the process of creating UIHook's, let's take a look at a basic comparison.

This is a UIHook created using a JavaScript template string:

const { withUiHook } = require('@zeit/integration-utils')

module.exports = withUiHook(({ payload }) => {
  return `
    <Page>
      Hello World
    </Page>
  `
})

An example of using a JavaScript template string to create a UIHook.

This is the same UIHook created using htm:

const { withUiHook, htm } = require('@zeit/integration-utils')

module.exports = withUiHook(({ payload }) => {
  return htm`
    <Page>
      Hello World
    </Page>
  `
})

An example of using htm to create a UIHook.

The key thing to note is the inclusion of htm just before the start of the JavaScript template string.

We have included a number of additional and more realistic use-cases in the next section.

Use Cases

As mentioned already, using htm can greatly simplify the process of creating UIHook's.

To help you understand the benefits of htm and how it differs slightly from JSX, we have created some examples below:

const { withUiHook, htm } = require('@zeit/integration-utils')

module.exports = withUiHook(({ payload }) => {
  const url = 'https://zeit.co'
  return htm`
    <Page>
      <Link href=${url}>ZEIT Homepage</Link>
    </Page>
  `
})

const { withUiHook, htm } = require('@zeit/integration-utils')

module.exports = withUiHook(({ payload }) => {
  const name = 'Arunoda Susirpala'
  return htm`
    <Page>
      <P>My name is ${name}</P>
    </Page>
  `
})

const { withUiHook, htm } = require('@zeit/integration-utils')

const urls = ['https://zeit.co', 'https://google.com']

module.exports = withUiHook(({ payload }) => {
  const name = 'Arunoda Susirpala'
  return htm`
    <Page>
      <UL>
        ${urls.map(url => htm`<LI>${url}</LI>`)}
      </UL>
    </Page>
  `
})

const { withUiHook, htm } = require('@zeit/integration-utils')

const urls = ['https://zeit.co', 'https://google.com']

const URL = ({ href }) => htm`
  <LI><Link href=${href} target="_blank">${href}</Link></LI>
`

module.exports = withUiHook(({ payload }) => {
  const name = 'Arunoda Susirpala'
  return htm`
    <Page>
      <UL>
        ${urls.map(url => htm`<${URL} href=${url} //>`)}
      </UL>
    </Page>
  `
})

Components

Inside an UIHook you can use a set of whitelisted components. These components will be parsed and rendered in the ZEIT Dashboard.

For security reasons, these components have some minor limitations:

• No HTML elements are allowed
• Script and Style tags are not supported
• JavaScript support is disabled
• Only a set of whitelisted components are supported

These limitations may seem restrictive, but with very good reason.

These limitations allow us to expose a way for you to introduce UI elements into the ZEIT Dashboard without requiring manual verification.

We also provide a set of rich components that allow you to receive user inputs, implement styling and even poll for changes.

Actions

In a user interface, we usually expose multiple different actions. In the example we looked at earlier there are two actions:

<Container>
  <Button action="submit">Submit</Button>
  <Button action="reset">Reset</Button>
</Container>

An example of a UIHook using whitelisted components.

These actions are exposed as buttons, in this case submit and reset.

When a user clicks a button, we send a request to the UIHook with the action. The UIHook then sends a response in the form of a string of components, this is what will be rendered.

You can access the action from the payload.action property. The default action is view and will always be the action when the Integration is first loaded.

For a better understanding of how actions work, take a look at the Counter example discussed earlier in the documentation.

You can discover all supported action components in the component catalog.

Client State

Just like actions, you need to be able to accept multiple different inputs from the user. This might include text boxes, password prompts, dropdowns - there are many options available.

This is how we can define an input field:

<Input name="username" value="my username" />

An example of a UIHook using an Input component.

Now the user can enter a value into this input.

When the user clicks on an action, we combine all of these inputs together into an object called clientState. For this example, if just the above input was submitted, the clientState would look like this:

{
  "username": "my username"
}

Inside the UIHook you can access this object via payload.clientState.

You can discover all supported input components in the component catalog.

Information

Tokens

Every request to a UIHook will receive a token which can be used to make requests to the ZEIT API for the related account.

This is a short-lived token. Therefore, you should only use it inside the UIHook. You should not use it inside asynchronous functions which are executed even after you return the UIHook response.

If you need a long-lived token, you can ask for a OAuth2 token.

You can access this property inside payload.token.

When you use the @zeit/integration-utils utility, you do not need to extract this token manually. You will receive an instance called zeitClient which is initialized with the above token and account information. You can use that to consume the ZEIT token.

This is how you can get that instance:

const { withUiHook } = require('@zeit/integration-utils')

module.exports = withUiHook(({ payload, zeitClient }) => {
  // Do something with the zeitClient and payload
  return `<Page>and return some JSX.</Page>`
})

You can inspect the API and methods of zeitClient to understand its capabilities.

Page

This is the root of your UIHook. All other components should live inside the Page component.

<Page>Some other components</Page>

Action Components

These components create a new UIHook request with an action that forms part of the component.

<Button action="create-db">Create Database</Button>

<ProjectSwitcher message="Choose a project from the list" />

<AutoRefresh timeout="<timeout-in-millis>" />

<Link href="https://zeit.co">Visit ZEIT</Link>

<Link action="doSomething">Do Something</Link>

<Select name="dbName" value="selectedValue" action="change-db">
  <Option value="mongodb" caption="MongoDB" />
  <Option value="redis" caption="Redis" />
</Select>

Input Components

To receive user inputs, you should use a component appropriate for your use case.

<Input name="dbName" label="Name for the Database" value="the default value" />

<Textarea name="description" label="Enter your description">
  The value
</Textarea>

<Select name="dbName" value="selectedValue">
  <Option value="mongodb" caption="MongoDB" />
  <Option value="redis" caption="Redis" />
</Select>

<Checkbox name="allowOptionA" label="Allow Option A" checked="true" />

<ClientState key1="value1" key2="value2" />

{
  "key1": "value1",
  "key2": "value2"
}

<ResetButton targets="username, password">Reset</ResetButton>

<Page>
  <Input type="text" name="username" />
  <Input type="text" name="password" />
  <Input type="text" name="age" />

  <Button action="submit">Submit</Button>
  <ResetButton targets="username, password">Reset</ResetButton>
</Page>

UI Components

The following UI components are very similar to those found in HTML5, the main difference being we're providing the initial styling.

<Box display="flex" justifyContent="space-between">
  <H1>Your Databases</H1>
  <Button>+Create New</Button>
</Box>

<P>A paragraph.</P>

<H1>The Title</H1>

<H2>The Secondary Title</H2>

<BR />

<HR />

<B>Some Bold Text</B>

<Img src="url-to-image" />

const code = `
    <html>You can put anything here</html>
`
<Code>${code}</Code>

<Fieldset>
  <FsContent>
    <H2>This is the Title</H2>
    <P>This is some content.</P>
  </FsContent>
  <FsFooter>
    <P>This is the footer.</P>
  </FsFooter>
</Fieldset>

<Notice type="error">This is an error messgae.</Notice>

Access via @zeit/integration-utils

If you use the @zeit/integration-utils helper to create the UIHook, you can access the Metadata Store via the zeitClient instance, for example:

const { withUiHook } = require('@zeit/integration-utils')

module.exports = withUiHook(async ({ payload, zeitClient }) => {
  // Get metadata
  const metadata = await zeitClient.getMetadata()
  metadata.count = metadata.count || 0
  metadata.count += 1

  // Set metadata
  await zeitClient.setMetadata(metadata)

  return `
    <Page>
    <P>Counter: ${metadata.count}</P>
      <Button>Count Me</Button>
    </Page>
  `
})

An example UIHook using the Metadata Store.

API

The following API endpoints can also be used to store metadata.

In order to use that API, you need to get the related configurationId. You can find that in the UIHook payload.

You must also provide an authorization token in the requests, further information is available here.

GET https://api.zeit.co/v1/integrations/configuration/:configurationId/metadata

{
  "user": {
    "username": "integrationuser",
    "name": "Integration User",
    "id": "id",
    "email": "mail@email.com"
  },
  "token": "token",
  "sandboxes": {
    "sandbox": "sandbox"
  }
}

POST https://api.zeit.co/v1/integrations/configuration/:configurationId/metadata

await fetch("https://api.zeit.co/v1/integrations/configuration/:configurationId/metadata", {
  "method": "POST",
  "body": "{\"mydata\": \"a value for mydata\"}"
})

Project-Based Environment Variables

When building a ZEIT Integration, you may want to expose an API secret or a configuration URL for deployments within a project.

For example, say you want to expose the MONGO_URL environment variable; the following would be the process to do so:

• Create a secret to store the value for MONGO_URL (This is an account wide operation). For this example, we'll assume the value for the secret key is mongo_url_for_my_db.
• Next, add MONGO_URL=@mongo_url_for_my_db for the projects where MONGO_URL is needed.

Utilities inside @zeit/integration-utils

If you are using @zeit/integration-utils to create your UIHook, the following example shows how to use utilities within your Integration:

const { withUiHook } = require('@zeit/integration-utils')

module.exports = withUiHook(async ({ payload, zeitClient }) => {
  if (payload.action === 'add-env') {
    const mongo_url = 'this is your mongo url'
    const secretName = await zeitClient.ensureSecret('mongo_url', mongo_url)
    await zeitClient.upsertEnv(payload.projectId, 'MONGO_URL', secretName)

    return `
      <Page>
        Environment variable added.
        <Button small action="view">Go Back</Button>
      </Page>
    `
  }

  return `
    <Page>
      <Button action="add-env">Add Env</Button>
    </Page>
  `
})

An example UIHook that uses @zeit/integration-utils utilities.

Based on the example above:

• zeitClient.ensureSecret will create a unique ZEIT secret based on the hash value of mongo_url, then returns the name of secret
• If the secret already exists, it will not be duplicated for the given value
• The value of secretName will be, for example; mongo_url_s2kj23jh55
• The secret is added to the project (using payload.projectId) through the zeitClient.upsertEnvmethod

Some considerations when using zeitClient.upsertEnv:

• In order to add a project level environment variable, there should be a projectId
• You can get the projectId from the payload object if the user is accessing the Integration installation from within a project
• Otherwise, if the user is inside a team view, you can hide the Add Env button or ask the user to switch to accessing the Integration from within a project

Using the API directly

If you are not using @zeit/integration-utils utility, you can use the ZEIT API directly. See the following API reference documentation for how to utilize it:

• Creating and Using Secrets
• Adding a New Environment Variable to a Project

Setting Up

The Delete Hook is a HTTP endpoint which is configured to receive HTTP DELETE requests. After you create the endpoint in your app, you can add it to the Integration via the Integration Console.

Inside your Integration's configuration page, there is an input to set the Delete Hook URL. This is where you should add the HTTP endpoint mentioned above.

With the Delete Hook URL set, when a user removes a configuration for your Integration, a HTTP DELETE request will be sent to the defined endpoint. The payload your delete endpoint receives is a JSON encoded HTTP body with the following fields:

• configurationId
• userId
• teamId - null if the user does not belong to a team

Take a look at this example integration to learn more about how Delete Hooks work.

HTTP Response

You should consider this HTTP request as an event. Once you receive the request, you should schedule a task for the cleanup action.

This request has a timeout of 10 seconds. That means, if a HTTP 200 response is not received within 10 seconds, the request will be aborted.

Terminology

There are some very specific terms used in relation to UIHooks, those being:

• "Integration": This is an Integration created using the ZEIT Dashboard. This is the what a user installs
• "Configuration": A single instance where a user added an Integration to an account (user or a team)
• "UIHook": An Integration can render UI elements. These UI elements are requested from a HTTP endpoint defined in the Integration's implementation. The HTTP endpoint is called a UIHook

UIHooks are HTTP-Based

UIHooks are HTTP based, therefore they are not tied to any programming language or framework.

The process a UIHook uses is as follows:

• The UIHook receives a HTTP POST request, including a JSON payload as the request body
• The UIHook returns a HTML string, with components, as the response
• A UIHook can be called via client side, so it needs to support CORS

The following example shows how you can implement a UIHook with Node.js and micro.

const micro = require('micro')

let counter = 0

async function uiHook(req, res) {
  // Add CORS support. So UIHook can be called via client side.
  res.setHeader('Access-Control-Allow-Origin', '*')
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS')
  res.setHeader(
    'Access-Control-Allow-Headers',
    'Authorization, Accept, Content-Type'
  )

  if (req.method === 'OPTIONS') {
    return micro.send(res, 200)
  }

  // UIHook works only with HTTP POST.
  if (req.method !== 'POST') {
    return micro.send(res, 404, '404 - Not Found')
  }

  // Extract payload from the POST body.
  const payload = await micro.json(req)
  if (payload.action === 'reset') {
    counter = 0
  } else {
    counter += 1
  }

  // Send HTML, with components, as the response
  return micro.send(
    res,
    200,
    `
    <Page>
      <P>Counter: ${counter}</P>
      <Button>Count Me</Button>
      <Button action="reset">Reset</Button>
    </Page>
  `
  )
}

// Start the HTTP server
const server = micro(uiHook)
const port = process.env.PORT || 5005

console.log(`UIHook started on http://localhost:${port}`)
server.listen(port, err => {
  if (err) {
    throw err
  }
})

For more examples of Integration implementations including the above example and others in more languages, such as PHP, Python, Go and Rust, see the Integration Gallery repository.

HTTP Payload

The payload used in the UIHook receives a JSON payload with different pieces of information regarding the related configuration of the Integration, those being:

• action - The action of the UIHook (defaults to view)
• clientState - An object containing the values of input components
• slug - The slug of the Integration that sent the request
• configurationId - The id of the configuration
• integrationId - The id of the Integration
• team - The team, if the Integration is added to a team
• user - The user object of the user who is accessing the configuration
• project - The project if the configuration is being accessing inside a project, otherwise null
• token - A short-lived token which has authorization for the installed account
• installationUrl - The URL of the current Integration configuration. (You can use this to redirect a user to another site using installationUrl as the redirect URL)
• query - An object containing query parameters of the Integration installation page

OAuth Support

With our OAuth support, you can connect your app with ZEIT or provide "login with ZEIT" functionality.

Every ZEIT Integration is a full-fledged OAuth app. You can add the redirect URL when either creating or editing an Integration, this will provide you with OAuth credentials.

You can then follow our OAuth API reference to build an OAuth Integration.

Hybrid Mode

Sometimes, your Integration will use a UIHook but also need to access the ZEIT API in a background worker.

In this situation you cannot use the UIHook's token since it is only valid for the execution period of the UIHook.

That's where Hybrid Mode comes in handy. Hybrid Mode is a combination of both UIHooks and OAuth. This is how it works:

• When you create your Integration, you can add both the Redirect URL and UI Hook URL
• You will receive a public URL for your Integration in the following format:

https://zeit.co/integration/:slug

• When the Integration installs, the OAuth authorization process is started
• The user is then sent to the Redirect URL

The Redirect URL supports the following query parameters:

• teamId - The teamId of the installation
• configurationId - The id of the related configuration
• code - OAuth authorization code (you can exchange an accessToken using this)
• next - The installation URL of your Integration in the ZEIT Dashboard

Now you can use UIHook's to display reports and receive inputs from the user. You can also use the obtained accessToken to access the ZEIT API from anywhere, at anytime.